@vectros-ai/mcp-server 0.17.0 → 0.17.1

package/dist/index.mjs

@@ -1,7 +1,7 @@
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 
-// ../../node_modules/@vectros-ai/sdk/dist/index.mjs
+// node_modules/@vectros-ai/sdk/dist/index.mjs
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -3400,6 +3400,7 @@ var AuthClient = class {
    *
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
@@ -3442,6 +3443,8 @@ var AuthClient = class {
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -3586,7 +3589,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/app-contexts/{contextId}");
   }
   /**
-   * Permanently deletes an app context and everything in it — every record, document, folder, schema, role, and access profile belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's `status` field to observe when the teardown completes (`purging` while draining, then `deleted`). To guard against accidental deletion, you must echo the contextId back in the `confirm` query parameter (`?confirm={contextId}`). The reserved `default` and `vectros-admin` contexts cannot be deleted. This operation requires a root API key (one beginning with `sk_`): no scoped credential, not even one with full wildcard (`*`) scope, can trigger this teardown.
+   * Permanently deletes an app context and everything in it — every record, document, folder, schema, role, access profile, and trusted-issuer registration belonging to the context. This is irreversible. The deletion runs asynchronously: the call returns 202 immediately and the context's data drains in the background. Poll the context's `status` field to observe when the teardown completes (`purging` while draining, then `deleted`). To guard against accidental deletion, you must echo the contextId back in the `confirm` query parameter (`?confirm={contextId}`). The reserved `default` and `vectros-admin` contexts cannot be deleted. This operation requires a root API key (one beginning with `sk_`): no scoped credential, not even one with full wildcard (`*`) scope, can trigger this teardown.
    *
    * @param {Vectros.DeleteAppContextRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4121,7 +4124,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers/{issuerId}");
   }
   /**
-   * Updates the mutable fields of a registered issuer: `subClaim`, `emailClaim`, `status` (`active`/`suspended` — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and `selfSignupPolicies`. Fields omitted from the body are left unchanged (partial update). `issuer`, `jwksUri`, `audience`, and `contextId` are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.
+   * Updates the mutable fields of a registered issuer: `subClaim`, `emailClaim`, `userinfoUri`, `capturedClaims`, `restrictedToDomain` (a new non-blank value must already be a VERIFIED domain for your account; an empty string clears it back to domain-less; see `IssuerUpdateRequest.restrictedToDomain` for the full semantics), `status` (`active`/`suspended` — a suspended issuer's tokens are rejected identically to an unregistered issuer at exchange time), and `selfSignupPolicies`. Fields omitted from the body are left unchanged (partial update). `issuer`, `jwksUri`, `audience`, and `contextId` are trust-anchor / routing-pin fields and are immutable via this route — supplying a value that differs from the current registration is rejected with 400; supplying the current value back is a no-op. Rotating a trust anchor requires deleting and re-registering the issuer, which is itself refused while any user is bound through it. **`subClaim` is identity-determining, not merely cosmetic**: it names which verified JWT claim is read as the federated user's identifier, so changing it on an issuer that already has bound users would silently re-identify (or, under self-signup, orphan) every one of them — changing it is therefore refused once any user has bound through this issuer, the same guard `DELETE` already applies, and is only free before the first real login. Requires a root API key or the bootstrap's provisioning capability, gated identically to every other operation on this surface. A credential confined to one app context may only update an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may update any issuer.
    *
    * @param {Vectros.IssuerUpdateRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4188,7 +4191,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/auth/issuers/{issuerId}");
   }
   /**
-   * Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through `POST /v1/auth/token/exchange`) — that access cannot be silently orphaned. Deactivate the affected users first if you intend to cut off their access, or register a replacement issuer before removing this one. An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.
+   * Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through `POST /v1/auth/token/exchange`) — that access cannot be silently orphaned. This is unconditional on the affected users' `status`: suspending them first does not lift the refusal. **A bound registration cannot be replaced, self-service, within its own app context**: registering a replacement issuer under a different issuerId in the SAME context also fails, because the context's one-active-issuer claim is released only when THIS registration is deleted. Two real options: suspend this issuer (stops new exchanges immediately) and register a replacement under a DIFFERENT app context — note that targets a different context, so this context's existing users/roles/access profiles are not carried over; or contact your platform operator, who can force-release this registration so a replacement may be registered in the SAME context under a new issuerId. **The operator path is not a lighter-weight alternative to the first — it PERMANENTLY RETIRES this issuerId and leaves every bound user unable to ever exchange through it again; it does not preserve continuity for them any better than registering under a different context does.** An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.
    *
    * @param {Vectros.DeleteIssuerRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4314,7 +4317,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers");
   }
   /**
-   * Registers a trusted third-party IdP issuer that BYO-IdP token exchange (`POST /v1/auth/token/exchange`) may accept a `subject_token` from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. A credential authorized only via the provisioning capability may register only against the app context it is bound to; naming a different one returns 403. A root API key is unaffected and may register against any of its contexts. Idempotent by `issuerId` within your tenant; the `(issuer, audience)` pair must not already be registered by a different issuerId/tenant. If `issuerId` collides with a registration owned by a different app context than the one you're confined to, the request fails with 400 rather than returning that context's configuration. An app context may have at most one active issuer — deregister the existing one first if you need to replace it. One issuer MAY serve several contexts today, each via its own registration row with a distinct `audience`.
+   * Registers a trusted third-party IdP issuer that BYO-IdP token exchange (`POST /v1/auth/token/exchange`) may accept a `subject_token` from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. A credential authorized only via the provisioning capability may register only against the app context it is bound to; naming a different one returns 403. A root API key is unaffected and may register against any of its contexts. Idempotent by `issuerId` within your tenant; the `(issuer, audience)` pair must not already be registered by a different issuerId/tenant. If `issuerId` collides with a registration owned by a different app context than the one you're confined to, the request fails with 400 rather than returning that context's configuration. An app context may have at most one active issuer — deregister the existing one first if you need to replace it. One issuer MAY serve several contexts today, each via its own registration row with a distinct `audience`. Optionally name `restrictedToDomain` to scope this registration's (issuer, audience) uniqueness to a specific VERIFIED domain rather than the bare pair — see that field's own description for the full contract, including why it does NOT protect a shared/consumer-IdP registration with no company-domain population.
    *
    * @param {Vectros.IssuerRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5812,7 +5815,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/{id}/versions");
   }
   /**
-   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata).
+   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL for the SAME existing document, targeting a newly-staged object rather than the document's current one — your PUT lands there first, and the document only adopts it once the upload is validated (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata). **Your PUT to `uploadUrl` MUST include the header named in the response's `requiredHeaderName`, set to `requiredHeaderValue` exactly.** It is a signed part of the presigned request — the PUT never reaches this service either way, so neither failure uses this API's JSON error shape. Omitting it, or sending a different value, invalidates the request's signature and S3 rejects it with a 403 `SignatureDoesNotMatch`. Sending it correctly makes the URL single-use: `requiredHeaderName` is always `If-None-Match` and `requiredHeaderValue` is always `*` — a create, a recovery upload for a document whose earlier file is missing, and a re-upload ALL target a freshly-minted, never-written key, so the same S3 conditional-write precondition applies uniformly (S3's own documented conditional-write behavior): a replay after the object already exists (from your own completed PUT, or anyone else's) fails with `412 Precondition Failed`; a replay after the object was deleted and never re-created finds an absent key again and can succeed — single-use is a property of the object's existence, not a one-time token. **Either precondition can also fail with `409 Conflict` if your PUT genuinely races a concurrent delete on the same object.** Whichever of `412` or `409` you receive, the remedy is the same: call this endpoint again for a fresh URL rather than retrying the same PUT — a fresh call always targets a new key, so it is never subject to whatever raced the previous one.
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7578,7 +7581,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users/exists-by-email");
   }
   /**
-   * Returns the audit trail of changes to a user, most recent first. Identity history is always recorded and always available. Sensitive field values are redacted in every historical version. Returns a page in the `{data, nextCursor}` envelope. Requires the `users:r` scope.
+   * Returns the audit trail of changes to a user, most recent first, including after the user has been deleted. Identity history is always recorded. Post-delete, this is readable by an account-level (root) API key only — a context-confined credential 404s after the delete, the same response it would get for a nonexistent id. Sensitive field values are redacted in every historical version. Returns a page in the `{data, nextCursor}` envelope. Requires the `users:r` scope.
    *
    * @param {Vectros.GetUserVersionsRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8648,7 +8651,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/records/lookup");
   }
   /**
-   * Returns the tombstone left behind when a record was hard-deleted, confirming the deletion and recording when it happened. Look it up using the deleted record's original ID. Requires the `records:r:<type>` scope.
+   * Returns the tombstone left behind when a record was hard-deleted, confirming the deletion and recording when it happened. Look it up using the deleted record's original ID. Requires the `records:r:<type>` scope, granted without a `data_scope` restriction: the owner of a deleted record cannot be checked, so a credential confined to an ownership compartment (e.g. `data_scope: {scope:org: [org_A]}`) cannot read tombstones, including for records it owned.
    *
    * @param {Vectros.GetRecordTombstoneRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9055,7 +9058,7 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/schemas/{id}");
   }
   /**
-   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. A lineage base (a schema other schemas declare `basedOn`) also cannot be deleted while any such variant still exists — delete the variant schema(s) first. It is likewise refused while any trigger rule fires off this schema — delete those trigger rules first. Requires the `schemas:d` scope.
+   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. The same applies to documents bound to this schema (for a schema declaring the `document` surface) — delete those documents first. A lineage base (a schema other schemas declare `basedOn`) also cannot be deleted while any such variant still exists — delete the variant schema(s) first. It is likewise refused while any trigger rule fires off this schema — delete those trigger rules first. Requires the `schemas:d` scope.
    *
    * @param {Vectros.DeleteSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9190,7 +9193,7 @@ var ScriptsClient = class {
    *
    * **Budget.** Seconds of useful work: the script has 15 s of wall clock (never more than 16) and a bounded number of statements and host calls; a runaway script is stopped early with `RESOURCE_LIMIT_EXCEEDED`. The transaction is bounded by the number of underlying storage rows it writes — 100 rows after merging — rather than by the number of entities: creating a folder costs 3 rows; creating a plain text document or a record costs 1 row plus one per range-indexed lookup field plus one per `reference` field. So "create a folder and file N documents" holds up to 97 plain documents, 48 with one range field or one reference, 32 with both; if a script exceeds the limit the error says so (`WRITE_BUFFER_CAP_EXCEEDED`, with `total` and `limit`) and nothing is committed. This request takes the write-path limits (burst, credit ceiling, principal quota) once, before the script runs — there is no free-read allowance here, so an account over its credit ceiling is refused even for a read-only script. Reads the script performs are metered as reads, writes as writes, and execution time beyond what those operations include is charged as script execution time (see `GET /v1/usage`).
    *
-   * **Reads inside the script.** A `get` sees the script's own staged writes. A list, query or lookup never shows a row the script has deleted, shows a row it re-saved with the updated content, and does not yet show a row it created — you hold that row's id from `create()`.
+   * **Reads inside the script.** A `get` sees the script's own staged writes. A list, query or lookup never shows a row the script has deleted, shows a row it re-saved with the updated content, and does not show a row it created — you hold that row's id from `create()`.
    *
    * **Retries.** Send an optional `Idempotency-Key` header (1–128 characters of letters, digits, `.`, `_`, `:` or `-`) to make a retry safe: a request repeated under the same key within 24 hours receives the same response as the first attempt without executing again — when that first attempt SUCCEEDED (a duplicate still in flight is refused with `409 IDEMPOTENCY_IN_PROGRESS`; the same key on a different request is refused with `422 IDEMPOTENCY_KEY_REUSED`). A first attempt that FAILED with any other status is not remembered: the same key is free to try again, so a retry after a `400` or a `429` executes. If an execution's outcome cannot be determined — the script did not finish inside the budget while its writes may have committed — the response is `500 EXECUTION_OUTCOME_UNKNOWN` carrying `execution.id`, and a keyed retry receives that same answer: inspect what the script would have written, then use a NEW key for a new attempt. When a key is present the serialised `result` is capped at 16 KB instead of 256 KB. Without a key, a lost response cannot be distinguished from a failed one; re-read before retrying.
    *
@@ -9285,11 +9288,14 @@ var ScriptsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/scripts/execute");
   }
   /**
-   * Returns a paginated list of your scripts. Pass `name` to list every version of one script name (oldest first); omit it for a flat list across every name in your account (newest first). Results are returned as a `{data, nextCursor}` envelope — pass `nextCursor` as `startFrom` to fetch the next page. Requires the `scripts:r` scope.
+   * Returns a paginated list of your scripts. Pass `name` to list every version of one script name (oldest first); omit it for a flat list across every name in your account (newest first). Results are returned as a `{data, nextCursor}` envelope — pass `nextCursor` as `startFrom` to fetch the next page. Requires the `scripts:r` scope. **Each row's `source` is omitted by default** (`sourceOmitted: true`) — scripts are immutable per version, so a name's version history can otherwise carry every version's complete source in one response. Pass `?includeSource=true` to get it back inline, or fetch one version's full source with a by-id GET. **`?name=<n>&latest=true`** answers "what is the current version of this name" in one bounded call — a single `ScriptResponse` object (not a page), instead of draining every page of the name's version history to find the newest yourself.
    *
    * @param {Vectros.ListScriptsRequest} request
    * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.NotFoundError}
+   *
    * @example
    *     await client.scripts.listScripts({
    *         name: "notify-assignee",
@@ -9300,11 +9306,13 @@ var ScriptsClient = class {
     return HttpResponsePromise.fromPromise(this.__listScripts(request, requestOptions));
   }
   async __listScripts(request = {}, requestOptions) {
-    const { name, startFrom, limit } = request;
+    const { name, startFrom, limit, includeSource, latest } = request;
     const _queryParams = {
       name,
       startFrom,
-      limit
+      limit,
+      includeSource,
+      latest
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -9330,16 +9338,23 @@ var ScriptsClient = class {
       return { data: _response.body, rawResponse: _response.rawResponse };
     }
     if (_response.error.reason === "status-code") {
-      throw new VectrosError({
-        statusCode: _response.error.statusCode,
-        body: _response.error.body,
-        rawResponse: _response.rawResponse
-      });
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/scripts");
   }
   /**
-   * Stores a new version of a script object. Every POST creates a genuinely new version — this is NOT idempotent-by-name: pushing `name` again always creates a new row with `scriptVersion` auto-incremented (the first version pushed for a name is 1). `source` is stored as-is: nothing parses or validates it at push time. A version runs when a trigger rule references it (`POST /v1/triggers`) or when `POST /v1/scripts/execute` names it. Requires the `scripts:c` scope.
+   * Stores a new version of a script object. Every POST creates a genuinely new version — this is NOT idempotent-by-name: pushing `name` again always creates a new row with `scriptVersion` auto-incremented (the first version pushed for a name is 1). `source` is stored as-is: nothing parses or validates it at push time. A version runs when a trigger rule references it (`POST /v1/triggers`) or when `POST /v1/scripts/execute` names it. `provisionedBy` MAY BE SET ON ABSENT, NEVER CHANGED, evaluated against the CURRENT LATEST version of this `name` at push time: if the latest version has no marker recorded, this push may set any value; if the latest version already has one, an omitted value inherits it forward and a DIFFERENT value is refused — a live comparison against whichever version is newest at push time, not a value fixed for the name's whole history. Pushing onto an EXISTING name with no `provisionedBy` recorded on its current latest version additionally requires that you were the caller who pushed that latest version — a name carrying a `provisionedBy` marker is exempt from this check (proving you can supply or inherit the matching marker is itself the ownership proof there). Requires the `scripts:c` scope.
    *
    * @param {Vectros.ScriptRequest} request
    * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -9526,12 +9541,13 @@ var ScriptsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/scripts/{id}");
   }
   /**
-   * Permanently deletes one script version by ID. Deleting one version does not affect any other version of the same name. Requires the `scripts:d` scope.
+   * Permanently deletes one script version by ID. Deleting one version does not affect any other version of the same name. Requires the `scripts:d` scope. Refused with 409 if a live trigger rule still references this version — either directly (a pinned `scriptRef`), or via `"latest"` when this IS the newest version of its name. Delete or re-point those rules first.
    *
    * @param {Vectros.DeleteScriptRequest} request
    * @param {ScriptsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
@@ -9571,6 +9587,8 @@ var ScriptsClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -10163,8 +10181,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.17.0" : "dev",
-  sdk: true ? "0.43.0" : "dev"
+  mcpServer: true ? "0.17.1" : "dev",
+  sdk: true ? "0.44.0" : "dev"
 };
 
 // src/log.ts
@@ -10500,6 +10518,8 @@ var hybridSearch = ({ client, log }) => ({
   title: "Hybrid search",
   description: 'Search your tenant\'s indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to `limit` results (default 3, max 50 \u2014 raise it in one call when you can accept the larger result) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId, and scope for ONE ownership dimension or scopeFilters for several at once \u2014 e.g. one client within one org), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller\'s scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents AND records are excluded from results \u2014 fetch them by id via document_get/record_get, or restore them by setting status back to ACTIVE. One exception to know: an item archived before the platform enforced this can still be returned here until it is next written to, and nothing sweeps for those \u2014 if an archived item does come back as a hit, re-send status ARCHIVED on it (document_update / record_update) to re-assert the retraction. A hit\'s `createdAt` is when the item entered the search INDEX, which is the moment it was created in the common case but is later for anything re-indexed since \u2014 so do not report it to a user as the creation time; fetch the item with document_get/record_get and read its own createdAt for that. (The createdAfter/createdBefore filters are a separate thing and do filter on true creation time.) To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). totalResults is the full matching pool and hasMore:true means results remain past this page \u2014 raise limit or advance offset to fetch them. textLegEmpty:true flags that the keyword (BM25) leg matched nothing (all textScores 0) \u2014 typically the default PHRASE mode finding no contiguous match for a long natural-language query. Loosen the keyword leg: shorten the query to its key terms, or set textMode "AND" (all terms, higher precision) or "OR" (any term, broad recall).',
   inputSchema,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
     const mode = args.mode ?? "HYBRID";
@@ -10648,6 +10668,8 @@ var recordQuery = ({ client, log }) => ({
   title: "Record query (list or lookup)",
   description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `values` (exact, composite \u2014 one value per field; a single-element array is the same as `value`), `from`+`to` (range), or `prefix`. `values` with more than one entry, or a comma-joined `field`, ONLY works for a lookup the schema itself declared over several fields together \u2014 check list_schemas' lookupFields for a fieldNames entry, then pass those field names comma-joined as `field`; `from`/`to`/`prefix` are not valid there. Works on sensitive fields too. Optionally narrow an exact match to a window with `sortFrom`/`sortTo`.\n  \u2022 List: omit `field`, then choose ONE of `type` (every record of a type), `folderId` (every record filed in a folder, any type \u2014 combine with `type` for one type within one folder), or `recent` (the account-wide recently-updated feed across every type, newest first \u2014 the only way to read records without naming a type, and standalone: no other filter applies to it). `userId`/`scope` further narrow the type and folder modes.\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. A composite lookup given fewer than its full field count returns records grouped by the unspecified fields, ordered within each group. Mode is auto-detected from the arguments present.",
   inputSchema: inputSchema2,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT2;
     const type = args.type;
@@ -10893,6 +10915,8 @@ var recordGet = ({ client, log }) => ({
   title: "Get a record by id or externalId",
   description: "Fetch a single structured record, including the full payload. Select it EITHER by its Vectros `id` (e.g. from record_query / hybrid_search) OR by your own `externalId` + `type` \u2014 the same key you passed to record_create, resolved for you (no manual record_query lookup needed). Very large payloads are truncated to protect the agent context window. The response carries the record's processing `indexStatus`; when it is FAILED an `indexFailure.code` explains whether the content is still searchable (e.g. VECTOR_LIMIT_EXCEEDED keeps keyword search vs INDEXING_FAILED = not findable at all) \u2014 branch on the `code`, not the message.",
   inputSchema: inputSchema3,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     const externalId = args.externalId;
@@ -10938,6 +10962,8 @@ var recordBatchGet = ({ client, log }) => ({
   title: "Get multiple records by id in one call",
   description: "Fetch several structured records by id in a single call (1-100 ids), each with its full payload \u2014 the same hydration record_get gives a single id. Use this instead of N record_get calls when you already hold several ids (e.g. a page of record_query/hybrid_search results). Any id you can't access is silently omitted from `data`; the response also returns `missingIds` \u2014 every requested id not present in `data` \u2014 so you can tell a partial result from a complete one. As with record_get, an oversized payload is truncated into a labelled `payloadPreview` rather than shipped whole.",
   inputSchema: inputSchema4,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const ids = args.ids;
     try {
@@ -10996,6 +11022,13 @@ var recordCreate = ({ client, log }) => ({
   title: "Create a record",
   description: "Create a structured record of a given type. Provide `type` and `fields` (the payload, validated against the type schema \u2014 call list_schemas first to learn required fields and enums). Idempotent by `externalId`. Requires the key to allow records:c (and records:r to receive the existing record on a collision).",
   inputSchema: inputSchema5,
+  // Creates, never modifies or deletes an existing record. Idempotent ONLY when the caller
+  // supplies `externalId` (optional, per the doc comment above) — re-creating with the same
+  // one returns the existing record rather than duplicating it. `externalId` is not required,
+  // so annotated for the less-safe default (omit it, and a retry creates a second record),
+  // not the safer opt-in — same standard applied to record_batch_write, which has the
+  // identical optional-externalId shape.
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args) => {
     const type = args.type;
     try {
@@ -11061,6 +11094,15 @@ var recordBatchWrite = ({ client, log }) => ({
   title: "Create or upsert multiple records in one call",
   description: 'Write up to 50 structured records in a single call \u2014 use this instead of N record_create calls when you hold several records (e.g. filing a parsed table, or seeding a set of tasks). Items may mix types; each one is schema-validated, externalId-idempotent and scope-checked individually against its own type (records:c:<type> per item), so a batch cannot write a type you could not write one at a time. `atomicity` chooses the commit shape: "best_effort" (default) writes each item independently; "all_or_nothing" commits every item in one transaction, writing nothing at all if any item fails \u2014 prefer it when a half-written set would be worse than none. IMPORTANT: this call reports success whenever the batch was PROCESSED, including when every item failed \u2014 so always read the per-item `results` and the `succeeded`/`failed` counts rather than treating a non-error result as "all written". This differs from record_create, where a failure is an error result. Results are NOT guaranteed to arrive in the order you submitted: match each one to its item by its `index` (zero-based, the position in your `items` array). A result carries the written record\'s `id` (null on failure) and, when it failed, an `error` with a machine-readable `code` and a human-readable `message` \u2014 read it before resubmitting. It does NOT carry the record itself; fetch that with record_get/record_batch_get. A per-item `status` is created (new record written), updated (an existing record matched \u2014 overwritten only if you passed upsert:true, otherwise returned unchanged, so this is not by itself evidence of a write), conflict (uniqueness or version), invalid (validation \u2014 read `error.message` for which field), forbidden (your credential lacks the scope or ownership that item needed \u2014 fix the credential, not the item), or not_committed (this item was fine but an all_or_nothing batch was aborted by a different item, so resubmitting with that one fixed writes this one unchanged).',
   inputSchema: inputSchema6,
+  // Creates by default, and can overwrite existing records as a FULL replacement when
+  // `upsert:true` is passed (destructive to whatever fields the old version carried and
+  // this call omits). Idempotent ONLY when every item supplies `externalId` (optional,
+  // per its own field doc above) — re-submitting then converges, with or without
+  // `upsert:true`. `externalId` is not required, so annotated for the less-safe default:
+  // an item with no `externalId` at all has no dedup key, and a resubmit creates a second
+  // record for it regardless of `upsert`. Same standard applied to record_create/
+  // document_ingest's identical optional-externalId shape.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
   handler: async (args) => {
     const items = args.items;
     const atomicity = args.atomicity;
@@ -11124,6 +11166,10 @@ var recordUpdate = ({ client, log }) => ({
   title: "Update a record by id or externalId",
   description: "Update a record \u2014 select it by its Vectros `id` OR by your own `externalId` + `type` (the same key you passed to record_create, resolved for you). The provided `fields` are DEEP-MERGED into the existing payload (unspecified fields are preserved; a field set to `null` is deleted). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Use `status` to archive without deleting. Requires the key to allow records:u.",
   inputSchema: inputSchema7,
+  // A JSON Merge Patch — overwrites the fields it names, so it can destroy a prior field
+  // value the caller did not mean to lose. Re-applying the same patch converges to the
+  // same state, so it is idempotent.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     const externalId = args.externalId;
@@ -11158,6 +11204,10 @@ var recordDelete = ({ client, log }) => ({
   title: "Delete a record",
   description: "Permanently delete a record by id (leaves a tombstone). Requires the key to allow records:d \u2014 a key without it gets a permission error. To archive without deleting, use record_update to set status instead.",
   inputSchema: inputSchema8,
+  // Deletes (leaves a tombstone server-side, but the record is gone from every normal
+  // read path). Idempotent in the standard REST sense: the end state ("this id no longer
+  // resolves") is the same whether this is the first delete or a repeat of one.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     try {
@@ -11220,6 +11270,15 @@ var ragAsk = ({ client, log }) => ({
   title: "RAG ask (corpus-wide)",
   description: "Ask a question grounded against your tenant's indexed content. Vectros performs a hybrid search, injects the top-K passages into the prompt, and streams a model answer back. Scope retrieval with `search` (ownership \u2014 `scope` for one ownership dimension or `scopeFilters` for several at once, e.g. one client within one org \u2014 folder, type, metadata filters, date window) to ground on a subset \u2014 e.g. one patient or one folder \u2014 and steer generation with `instructions` / `temperature`. The full answer is returned as a single response; progress notifications keep the call alive during the 30-45s generation window. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
   inputSchema: inputSchema9,
+  // NOT a pure read: this call reserves an atomic hold against the caller's prepaid inference
+  // balance before generation starts, then debits it on completion — a real financial side
+  // effect that can trigger a configured auto-recharge against the tenant's card.
+  // `readOnlyHint:true` would let a host
+  // skip a confirmation prompt on a call with real, unbounded-under-retry spend; ordinary reads
+  // that merely meter usage stay `readOnlyHint:true` (hybrid_search has no inference-cost leg),
+  // but a call that can debit a balance and possibly charge a card is a different class. Not
+  // idempotent either: every repeat charges again, and generation is non-deterministic.
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args, extra) => {
     const rawSearch = args.search ?? {};
     if (rawSearch.scope !== void 0 && rawSearch.scopeFilters !== void 0) {
@@ -11319,6 +11378,15 @@ var documentAsk = ({ client, log }) => ({
   title: "Document ask (single-document)",
   description: "Ask a question against a single indexed document. Returns a grounded answer with the document context that informed it. For documents exceeding the input-token cap, the API returns a structured 413 with `estimatedTokens` and `limitTokens`. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
   inputSchema: inputSchema10,
+  // NOT a pure read: this call reserves an atomic hold against the caller's prepaid inference
+  // balance before generation starts, then debits it on completion — a real financial side
+  // effect that can trigger a configured auto-recharge against the tenant's card.
+  // `readOnlyHint:true` would let a host
+  // skip a confirmation prompt on a call with real, unbounded-under-retry spend; ordinary reads
+  // that merely meter usage stay `readOnlyHint:true` (hybrid_search has no inference-cost leg),
+  // but a call that can debit a balance and possibly charge a card is a different class. Not
+  // idempotent either: every repeat charges again, and generation is non-deterministic.
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args, extra) => {
     try {
       const stream = await client.inference.documentAsk({
@@ -11397,6 +11465,8 @@ var listSchemas = ({ client, log }) => ({
   title: "List record schemas",
   description: 'List the structured-record schema catalog for your tenant. Each schema describes a record type (e.g. "patient", "clinical_note") \u2014 its fields, lookup-indexed fields, and capabilities. Use this to discover what record types exist before calling `record_query`. Filter with `surface` (record/document/user/entity \u2014 e.g. only document types), `recordType` (resolve one schema by its type name), or `userId`/`scope`; default returns everything the credential can see.',
   inputSchema: inputSchema11,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const userId = args.userId;
     const scope = args.scope;
@@ -11451,6 +11521,8 @@ var documentGet = ({ client, log }) => ({
   title: "Get document metadata (and optionally text)",
   description: "Fetch metadata for a single document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). Text is available for every text-ingested document and for file-ingested documents unless they were uploaded with `storeText: false` (extracted text discarded after indexing) \u2014 then `textAvailable: false` is set; the original file is still retrievable via `includeDownloadUrl`. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns the full document metadata, including its lifecycle `status` (ACTIVE, or ARCHIVED when soft-retracted from search \u2014 restorable via document_update) and its processing `indexStatus`. When `indexStatus` is FAILED the response also carries `indexFailure` with a machine-readable `code` telling you whether the content is still findable \u2014 e.g. TEXT_INDEX_FAILED / VECTOR_LIMIT_EXCEEDED (one leg still serves it) vs INDEXING_FAILED (not findable by search at all). Branch on `code`, not on the message.",
   inputSchema: inputSchema12,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const documentId = args.documentId;
     const externalId = args.externalId;
@@ -11545,6 +11617,8 @@ var documentQuery = ({ client, log }) => ({
   title: "Document query (list or lookup)",
   description: "Query document metadata. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields (equality only there); range/prefix need a range-enabled field.\n  \u2022 List: omit `field`; optionally filter by `folderId`/`userId`/`scope` (`namespace:value`).\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` documents (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected. Use document_get for the full text/download URL of one document.",
   inputSchema: inputSchema13,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT3;
     const field = args.field;
@@ -11655,6 +11729,10 @@ var documentUpdate = ({ client, log }) => ({
   title: "Update a document",
   description: 'Update a document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). `fields` are DEEP-MERGED into the existing typed payload (unspecified fields preserved; a field set to `null` is deleted); title/folderId/status/ownership are updated when provided and preserved otherwise. Supply `text` to re-ingest and re-index the document body in place (text documents only). Set `status: "ARCHIVED"` to soft-retract a document (pulled from search, kept and recoverable) and `status: "ACTIVE"` to restore it. Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Requires the key to allow documents:u.',
   inputSchema: inputSchema14,
+  // A JSON Merge Patch — overwrites the fields it names, so it can destroy a prior field
+  // value the caller did not mean to lose. Re-applying the same patch converges to the
+  // same state, so it is idempotent.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const documentId = args.documentId;
     const externalId = args.externalId;
@@ -11703,6 +11781,9 @@ var documentDelete = ({ client, log }) => ({
   title: "Delete a document",
   description: 'Permanently delete a document by id (removes it and its indexed content). Requires the key to allow documents:d \u2014 a key without it gets a permission error. To archive without deleting, use document_update to set status: "ARCHIVED" instead (recoverable, and needs no delete authority).',
   inputSchema: inputSchema15,
+  // Deletes. Idempotent in the standard REST sense: the end state ("this id no longer
+  // resolves") is the same whether this is the first delete or a repeat of one.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const documentId = args.documentId;
     try {
@@ -11740,6 +11821,8 @@ var folderQuery = ({ client, log }) => ({
   title: "Folder query (list or get)",
   description: "Read folders. Two modes:\n  \u2022 Get: pass `id` \u2192 returns the single folder.\n  \u2022 List: omit `id`; pass `parentId` for a folder's direct children (tree navigation) or omit for a flat tenant list. Optionally filter by `userId` or `scope` (`namespace:value`).\nList mode returns `{ data, nextCursor }` (default 10, max 100 per page \u2014 raise it in one call when you can accept the larger page); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page through all folders. Get mode returns the single folder object.",
   inputSchema: inputSchema16,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     try {
@@ -11774,7 +11857,9 @@ var inputSchema17 = {
   name: z17.string().min(1, "name is required").describe("Folder display name."),
   description: z17.string().optional().describe("Optional description of the folder's purpose."),
   parentId: z17.string().optional().describe("Parent folder id \u2014 places the folder under this parent. Omit for the context default root. Create-only."),
-  slug: z17.string().optional().describe("Optional stable slug (sibling-unique; idempotency key). Lowercase letters/digits/hyphens. Derived from name when omitted."),
+  slug: z17.string().optional().describe(
+    "Optional stable slug (sibling-unique; idempotency key). Lowercase letters/digits/hyphens. SUPPLY THIS to make a retry safe \u2014 if omitted, a derived slug is only ever a freshly-proved-free one, so a redelivered call creates a new sibling folder every time rather than matching the first."
+  ),
   userId: z17.string().optional().describe("Owning user (Vectros UUID)."),
   scopes: z17.array(z17.string()).optional().describe(
     'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the folder\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE folder owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
@@ -11783,8 +11868,18 @@ var inputSchema17 = {
 var folderCreate = ({ client, log }) => ({
   name: "folder_create",
   title: "Create a folder",
-  description: "Create a folder to organize documents and records. Pass `parentId` to nest it (create-only \u2014 folders cannot be moved later). Idempotent by `slug` within the parent. Requires the key to allow folders:c (and folders:r to receive the existing folder on a collision).",
+  description: "Create a folder to organize documents and records. Pass `parentId` to nest it (create-only \u2014 folders cannot be moved later). Idempotent by `slug` within the parent ONLY when you pass `slug` explicitly \u2014 omitting it derives a fresh, always-free slug on every call, so a retry creates a new sibling folder rather than matching the first. Requires the key to allow folders:c (and folders:r to receive the existing folder on a collision).",
   inputSchema: inputSchema17,
+  // Idempotent ONLY when the caller supplies `slug` explicitly (see the doc comment above): an
+  // omitted slug is derived through a collision-probing suffix loop that returns only a
+  // freshly-proved-free value, so the idempotency check running after that derivation can never
+  // match on the default path. `slug` is optional, so this is annotated for the less-safe default —
+  // the same standard applied to record_create/document_ingest/record_batch_write's identical
+  // optional-dedupe-key shape. (A prior version of this annotation claimed unconditional
+  // idempotency, reasoning that the derived slug made this tool "genuinely structurally different"
+  // from the optional-externalId tools — that reasoning was wrong: the derivation is unconditional,
+  // but it is unconditionally NON-colliding by construction, which is the opposite property.)
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
   handler: async (args) => {
     try {
       const folder = await client.folders.createFolder({
@@ -11826,6 +11921,10 @@ var folderUpdate = ({ client, log }) => ({
   title: "Update a folder",
   description: "Update a folder's name / description / ownership by id (RFC-7386 merge \u2014 omitted fields preserved). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Folders cannot be moved (re-parenting is not supported by the API). Requires the key to allow folders:u.",
   inputSchema: inputSchema18,
+  // A JSON Merge Patch — overwrites the fields it names, so it can destroy a prior field
+  // value the caller did not mean to lose. Re-applying the same patch converges to the
+  // same state, so it is idempotent.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     const name = args.name;
@@ -11861,6 +11960,9 @@ var folderDelete = ({ client, log }) => ({
   title: "Delete a folder",
   description: 'Permanently delete a folder by id. The folder must be EMPTY first \u2014 it must contain no documents, no records, and no sub-folders \u2014 and a non-empty folder is refused, which is the most common way this call fails. Use record_query with this folderId, and document_query, to see what is in it. Clearing it differs by content type: a document can be moved out (document_update with a different folderId) or deleted. A RECORD can also be re-filed into another folder \u2014 the API supports it \u2014 but THIS SERVER does not expose that yet: record_update has no folderId argument, so from here your only option is record_delete (needs records:d). Do NOT read that as "the record cannot be moved" and delete partner data on that basis: if the record should be kept, move it with the Vectros API/SDK directly rather than deleting it here. A sub-folder cannot be re-parented at all, so nested folders have to be emptied and deleted innermost-first. Note the emptiness check counts everything in the folder, INCLUDING items your credential cannot read \u2014 so a refusal you cannot account for from what you can list is expected behaviour, not a bug, and retrying will not clear it. Requires the key to allow folders:d \u2014 a key without it gets a permission error. Protected folders (e.g. a context root) cannot be deleted at all, however empty.',
   inputSchema: inputSchema19,
+  // Deletes. Idempotent in the standard REST sense: the end state ("this id no longer
+  // resolves") is the same whether this is the first delete or a repeat of one.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
   handler: async (args) => {
     const id = args.id;
     try {
@@ -11884,6 +11986,8 @@ var currentIdentity = ({ log, apiKey, environment }) => ({
   title: "Current identity (tenant + principal scope)",
   description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's verb+ownership reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Note: this does not yet include granted_capabilities (member-lifecycle / forensic-read / context-directory-read / delegate-mint, as of API 0.40.0, joined by delegate-principal-stamp in 0.42.0) \u2014 a separate reach dimension a scope clause can carry that /v1/ping does not report yet, so allowedActions+dataScope may understate a credential's true reach. Also reports mcpServerVersion (this server's own package version) and sdkVersion (the bundled @vectros-ai/sdk version) so a caller can tell what build it's talking to. Use this when the user asks 'what can you do here?', 'what tenant am I in?', or 'what version is this?'. Calls GET /v1/ping under the hood.",
   inputSchema: inputSchema20,
+  // A pure read (/v1/ping) — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async () => {
     try {
       const identity = await resolveIdentity({ log, apiKey, environment });
@@ -12013,6 +12117,16 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
   title: "Ingest a new document (text body or file upload)",
   description: "Create a new document in your Vectros tenant. Two modes:\n  \u2022 Text mode: pass `text` (string body). Single-call. Use for crawled content, notes, generated text.\n  \u2022 File mode: pass `filePath` (local path on the MCP server's host machine). STDIO-TRANSPORT ONLY \u2014 rejected on HTTP transport. MCP server reads the bytes, requests a presigned upload URL, and PUTs them. Returns when the upload is accepted (indexStatus: PENDING_INDEX); poll with `document_get` until indexStatus is INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate \u2014 requires documents:r in addition to documents:c, since being handed the existing document is a read of it). To UPDATE an existing document instead \u2014 re-index an edited body \u2014 pass `upsert:true` with the same `externalId` (and the same `schemaId`); this is the re-sync primitive for keeping a knowledge base current. Pass `schemaId` + `payload` for a typed, lookup-queryable document (records parity). indexMode defaults to HYBRID for untyped documents (omit to inherit a bound schema's default). storeText is a FILE-MODE knob (default true): false discards the uploaded file's extracted text after indexing (search + file download keep working; text retrieval and document_ask do not). Text-mode bodies are always retained, so storeText is not accepted with `text`.",
   inputSchema: inputSchema21,
+  // Creates by default, idempotent ONLY when the caller supplies `externalId` (optional,
+  // per the doc comment above) — re-ingest then returns the existing document rather than
+  // duplicating it. `externalId` is not required, so annotated for the less-safe default
+  // (omit it, and every call creates a new document), same standard applied to
+  // record_create/record_batch_write's identical optional-externalId shape. `upsert:true`
+  // is a further, real, named capability of this tool that OVERWRITES an existing
+  // document's content and re-indexes it — that path is destructive to the prior body, so
+  // this is flagged destructive rather than claiming create-only safety a caller can
+  // invoke past.
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
   handler: async (args) => {
     const title = args.title;
     const text = args.text;
@@ -12123,7 +12237,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       }
       const putRes = await fetch(uploadUrl, {
         method: "PUT",
-        headers: { "Content-Type": fileType },
+        headers: { "Content-Type": fileType, ...presignedUploadHeaders(upload) },
         body: bytes
       });
       if (!putRes.ok) {
@@ -12162,6 +12276,13 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
   }
 });
 var document_ingest_default = documentIngest;
+function presignedUploadHeaders(response) {
+  if (typeof response !== "object" || response === null) return {};
+  const { requiredHeaderName, requiredHeaderValue } = response;
+  if (typeof requiredHeaderName !== "string" || requiredHeaderName === "") return {};
+  if (typeof requiredHeaderValue !== "string") return {};
+  return { [requiredHeaderName]: requiredHeaderValue };
+}
 
 // src/tools/lookup_principal.ts
 import { z as z21 } from "zod";
@@ -12195,6 +12316,8 @@ var lookupPrincipal = ({ client, log }) => ({
   title: "Look up a user identity or a namespaced identity entity",
   description: "Resolve a user, or an identity entity in a namespace (org/client/one you registered). Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) For an entity kind, `contextId` names a specific app context when the namespace is context-owned rather than tenant-wide; a context-confined credential's own context is used automatically without it. Returns a `{ data, nextCursor }` page (default 10, max 100 \u2014 raise it in one call when you can accept the payload); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom`. Read-only \u2014 does not create or modify identities.",
   inputSchema: inputSchema22,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const kind = args.kind;
     const isUser = kind === "user";
@@ -12279,6 +12402,8 @@ var versionHistory = ({ client, log }) => ({
   title: "Version history (record or document)",
   description: "Read the audit/version trail (CREATE/UPDATE/DELETE, with actor, timestamp, and diff) for a single record or document. Pass `resourceType` (record|document) and `id`. Returns `{ data, nextCursor }`; pass `nextCursor` back as `startFrom` to page through older entries. Entities without audit history (untyped) return an empty trail. Read-only.",
   inputSchema: inputSchema23,
+  // A pure read — never creates, modifies, or deletes anything server-side.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
   handler: async (args) => {
     const resourceType = args.resourceType;
     const id = args.id;
@@ -12556,7 +12681,12 @@ var VectrosMCPServer = class {
           // MCP client (a well-behaved client rejects an unknown key before the call).
           // The server enforces it too (z.object(...).strict() below) so a raw JSON-RPC
           // call that skips client validation is still rejected — belt and suspenders.
-          inputSchema: { ...zodShapeToJsonSchema(t.inputSchema), additionalProperties: false }
+          inputSchema: { ...zodShapeToJsonSchema(t.inputSchema), additionalProperties: false },
+          // Forwarded from the tool's own definition, not hand-copied here: adding an
+          // annotation to a tool factory does nothing for a client unless it also reaches
+          // this emitted list — the actual `tools/list` response a host reads, not the
+          // source that builds it.
+          ...t.annotations ? { annotations: t.annotations } : {}
         }))
       })
     );