Rename the job-status tools to -get; crawl-cancel is destructive

CHANGELOG.md

@@ -7,7 +7,8 @@ All notable changes to this package are documented here. For cross-SDK release n
 ### Changed
 - OAuth connections (`/mcp/oauth`: ChatGPT, Claude.ai) list every offered tool up front and no longer carry `ethora-tools-enable`; the server-integration groups (keys, session, b2b, legacy-bot) are not offered there at all. Directory scanners require each model-callable operation to be its own listed tool. The open and personal-URL entries keep the compact core plus `ethora-tools-enable`.
 - `openWorldHint` is true for every tool that calls the Ethora API (an independently operated system from the client's point of view) or fetches a website, and false only for the tools that run inside the server (status, help, app-select, search, fetch, session configuration, text generators).
-- `destructiveHint` is true for the crawl, re-index, refresh and knowledge-rebuild tools: they replace stored pages or index entries (the crawl tools only with `force`).
+- `destructiveHint` is true for the crawl, re-index, refresh and knowledge-rebuild tools: they replace stored pages or index entries (the crawl tools only with `force`); and for `ethora-source-site-crawl-cancel`, which discards the unfinished part of a crawl.
+- `ethora-broadcast-job-start` and `ethora-user-batch-job-start` are renamed `ethora-broadcast-job-get` and `ethora-user-batch-job-get`: they fetch a job's state by id and never started anything. The old names stay as aliases.
 
 ## 26.10.1 - 2026-10-16
 

README.md

@@ -151,11 +151,11 @@ Three ways to get more:
 | `keys` | List and revoke API keys, reveal an app's credentials, mint and rotate app tokens. | `ethora-api-key-list`, `ethora-api-key-revoke`, `ethora-app-credentials-reveal`, `ethora-app-token-create`, `ethora-app-token-list`, `ethora-app-token-revoke`, `ethora-app-token-rotate` |
 | `session` | Diagnostics, recipes and switching the session's auth mode (app token, B2B token) for server integrations. | `ethora-doctor`, `ethora-recipe-run`, `ethora-session-configure`, `ethora-auth-mode-set`, `ethora-auth-mode-set`, `ethora-auth-mode-set` |
 | `apps-admin` | Delete, export and import whole apps; inspect default rooms. | `ethora-app-delete`, `ethora-app-export`, `ethora-app-import`, `ethora-app-rooms-list`, `ethora-app-rooms-list` |
-| `rooms` | Delete rooms, broadcast to many rooms, search messages, read message context and unread counts. | `ethora-chat-delete`, `ethora-broadcast-send`, `ethora-broadcast-job-start`, `ethora-broadcast-job-wait`, `ethora-message-search`, `ethora-message-context`, `ethora-chat-unread-counts` |
+| `rooms` | Delete rooms, broadcast to many rooms, search messages, read message context and unread counts. | `ethora-chat-delete`, `ethora-broadcast-send`, `ethora-broadcast-job-get`, `ethora-broadcast-job-wait`, `ethora-message-search`, `ethora-message-context`, `ethora-chat-unread-counts` |
 | `agents-admin` | Inspect, clone (with or without its knowledge), delete, export and import agents; try an agent without a room; check and rebuild its knowledge index; edit its Memory and visibility. | `ethora-agent-get`, `ethora-agent-clone`, `ethora-agent-delete`, `ethora-agent-export`, `ethora-agent-import`, `ethora-agent-visibility-set`, `ethora-agent-soul-set`, `ethora-agent-soul-append`, `ethora-agent-try`, `ethora-agent-knowledge-get`, `ethora-agent-knowledge-rebuild` |
 | `sources` | Knowledge-base maintenance: async crawl and reindex jobs, stop a crawl, list and tag sites and documents, delete URLs and documents. | `ethora-source-site-crawl`, `ethora-source-site-crawl-cancel`, `ethora-source-site-reindex`, `ethora-source-site-reindex-wait`, `ethora-source-site-list`, `ethora-source-site-watch-list`, `ethora-source-site-watch-update`, `ethora-source-site-refresh`, `ethora-source-site-tags-update`, `ethora-source-site-url-delete`, `ethora-source-site-url-delete-batch`, `ethora-source-doc-list`, `ethora-source-doc-tags-update`, `ethora-source-doc-delete` |
 | `widget` | Read and change the website widget's saved look (colours, fonts, size, launcher, teaser, texts); live embeds pick it up without a new snippet. | `ethora-widget-appearance-get`, `ethora-widget-appearance-set` |
-| `users-files` | Batch-create users and upload, fetch or delete files. | `ethora-user-batch-create`, `ethora-user-batch-job-start`, `ethora-user-batch-job-wait`, `ethora-file-upload`, `ethora-file-get`, `ethora-file-delete` |
+| `users-files` | Batch-create users and upload, fetch or delete files. | `ethora-user-batch-create`, `ethora-user-batch-job-get`, `ethora-user-batch-job-wait`, `ethora-file-upload`, `ethora-file-get`, `ethora-file-delete` |
 | `legacy-bot` | The per-app bot of apps created in the dashboard before the agents framework, and the pre-v2 document tools. Prefer the agents and sources tools for anything new. | `ethora-bot-get`, `ethora-bot-update`, `ethora-bot-enable`, `ethora-bot-disable`, `ethora-bot-widget-get`, `ethora-bot-history`, `ethora-bot-message-send`, `ethora-bot-instance-list`, `ethora-bot-instance-status-set`, `ethora-bot-instance-diagnose`, `ethora-bot-instance-leave`, `ethora-bot-instance-test`, `ethora-bot-enable-b2b`, `ethora-source-doc-upload-legacy`, `ethora-source-doc-delete-legacy` |
 | `b2b` | Server-to-server provisioning with a B2B token, plus code and config generators for integrations. | `ethora-b2b-app-create`, `ethora-b2b-app-provision`, `ethora-b2b-app-bootstrap-ai`, `ethora-b2b-runbook-generate`, `ethora-env-examples-generate`, `ethora-chat-component-app-generate`, `ethora.b2b.auth.use`, `ethora.b2b.app.create`, `ethora.b2b.bot.enable`, `ethora.b2b.broadcast.wait`, `ethora.b2b.app.bootstrap-ai` |
 | `wallet` | Wallet balance and ERC-20 transfer. Local (stdio) only; never offered on the hosted server. | `ethora-wallet-balance-get`, `ethora-wallet-erc20-transfer` |
@@ -406,7 +406,7 @@ Names used before 27.0 and the tool each one now resolves to. All of them remain
 | `ethora-bot-message-v2` | `ethora-bot-message-send` |
 | `ethora-bot-update-v2` | `ethora-bot-update` |
 | `ethora-bot-widget-v2` | `ethora-bot-widget-get` |
-| `ethora-chats-broadcast-job-v2` | `ethora-broadcast-job-start` |
+| `ethora-chats-broadcast-job-v2`, `ethora-broadcast-job-start` | `ethora-broadcast-job-get` |
 | `ethora-wait-broadcast-job-v2` | `ethora-broadcast-job-wait` |
 | `ethora.b2b.broadcast.wait` | `ethora-broadcast-job-wait` |
 | `ethora-chats-broadcast-v2` | `ethora-broadcast-send` |
@@ -439,7 +439,7 @@ Names used before 27.0 and the tool each one now resolves to. All of them remain
 | `ethora-sources-site-delete-url-v2` | `ethora-source-site-url-delete` |
 | `ethora-sources-site-delete-url-v2-batch` | `ethora-source-site-url-delete-batch` |
 | `ethora-users-batch-create-v2` | `ethora-user-batch-create` |
-| `ethora-users-batch-job-v2` | `ethora-user-batch-job-start` |
+| `ethora-users-batch-job-v2`, `ethora-user-batch-job-start` | `ethora-user-batch-job-get` |
 | `ethora-wait-users-batch-job-v2` | `ethora-user-batch-job-wait` |
 | `ethora-wallet-get-balance` | `ethora-wallet-balance-get` |
 | `ethora-widget-embed-snippet` | `ethora-widget-snippet-get` |

docs/TOOL_ANNOTATIONS.md

@@ -118,7 +118,7 @@ The hosted server (`mcp.chat.ethora.com`) never lists the stdio-only wallet tool
 
 | Tool | Read-only | Destructive | Idempotent | Open world | Why |
 |---|---|---|---|---|---|
-| `ethora-broadcast-job-start` | yes | no | yes | yes | Fetches the status and per-room results of a broadcast job by id (the name is historical); stores nothing. |
+| `ethora-broadcast-job-get` | yes | no | yes | yes | Fetches the status and per-room results of a broadcast job by id; stores nothing. |
 | `ethora-broadcast-job-wait` | yes | no | yes | yes | Polls a broadcast job until it finishes and returns its results; stores nothing. |
 | `ethora-broadcast-send` | no | no | no | yes | Posts one message into many rooms of the app, reaching their members; every call posts again. |
 | `ethora-chat-delete` | no | yes | yes | yes | Deletes a chat room and its messages; deleting twice changes nothing more. |
@@ -143,7 +143,7 @@ The hosted server (`mcp.chat.ethora.com`) never lists the stdio-only wallet tool
 | `ethora-source-doc-list` | yes | no | yes | yes | Lists the knowledge documents of the app or agent; stores nothing. |
 | `ethora-source-doc-tags-update` | no | yes | yes | yes | Replaces the retrieval tags of a document (not additive); the same tags twice give the same result. |
 | `ethora-source-site-crawl` | no | yes | no | yes | Fetches pages from an external website and stores them as agent knowledge; with `force` it replaces the stored copy of an already indexed page, which cannot be undone, and every call starts a new crawl. |
-| `ethora-source-site-crawl-cancel` | no | no | yes | yes | Stops a running crawl job; stopping twice changes nothing more and nothing is deleted. |
+| `ethora-source-site-crawl-cancel` | no | yes | yes | yes | Stops a running crawl job and discards the pages it had not finished storing, which cannot be resumed (a new crawl can be started); cancelling twice changes nothing more. |
 | `ethora-source-site-list` | yes | no | yes | yes | Lists the crawled pages of the app or agent; stores nothing. |
 | `ethora-source-site-refresh` | no | yes | no | yes | Re-crawls a whole site or named pages now and replaces their stored content; every call fetches again. |
 | `ethora-source-site-reindex` | no | yes | no | yes | Re-fetches one indexed URL from its website and replaces its stored content, so the previous copy is gone; every call fetches again. |
@@ -162,7 +162,7 @@ The hosted server (`mcp.chat.ethora.com`) never lists the stdio-only wallet tool
 | `ethora-file-get` | yes | no | yes | yes | Returns a file's metadata and download location; stores nothing. |
 | `ethora-file-upload` | no | no | no | yes | Stores a new file in the app's storage; every call stores another copy. |
 | `ethora-user-batch-create` | no | no | no | yes | Creates several users in the app from a list; every call creates more users (duplicates are reported, not created). |
-| `ethora-user-batch-job-start` | yes | no | yes | yes | Fetches the status and per-user results of a users batch job by id (the name is historical); stores nothing. |
+| `ethora-user-batch-job-get` | yes | no | yes | yes | Fetches the status and per-user results of a users batch job by id; stores nothing. |
 | `ethora-user-batch-job-wait` | yes | no | yes | yes | Polls a users batch job until it finishes; stores nothing. |
 
 ## Group `widget`

src/toolAnnotations.ts

@@ -102,14 +102,14 @@ export const TOOL_ANNOTATIONS: Record<string, ToolAnnotation> = {
   "ethora-message-context": READ("Returns the messages around one message; stores nothing."),
   "ethora-chat-unread-counts": READ("Returns unread counts per room; stores nothing."),
   "ethora-broadcast-send": A(false, false, false, true, "Posts one message into many rooms of the app, reaching their members; every call posts again."),
-  "ethora-broadcast-job-start": READ("Fetches the status and per-room results of a broadcast job by id (the name is historical); stores nothing."),
+  "ethora-broadcast-job-get": READ("Fetches the status and per-room results of a broadcast job by id; stores nothing."),
   "ethora-broadcast-job-wait": READ("Polls a broadcast job until it finishes and returns its results; stores nothing."),
   "ethora-bot-message-send": A(false, false, false, true, "Legacy alias of ethora-message-send: posts a message into a room; every call posts again."),
   "ethora-bot-history": READ("Legacy alias of ethora-chat-history; stores nothing."),
 
   // Users and files
   "ethora-user-batch-create": CREATE("Creates several users in the app from a list; every call creates more users (duplicates are reported, not created)."),
-  "ethora-user-batch-job-start": READ("Fetches the status and per-user results of a users batch job by id (the name is historical); stores nothing."),
+  "ethora-user-batch-job-get": READ("Fetches the status and per-user results of a users batch job by id; stores nothing."),
   "ethora-user-batch-job-wait": READ("Polls a users batch job until it finishes; stores nothing."),
   "ethora-file-upload": CREATE("Stores a new file in the app's storage; every call stores another copy."),
   "ethora-file-get": READ("Returns a file's metadata and download location; stores nothing."),
@@ -146,7 +146,7 @@ export const TOOL_ANNOTATIONS: Record<string, ToolAnnotation> = {
   // Knowledge sources
   "ethora-source-site-crawl": REPLACE_JOB("Fetches pages from an external website and stores them as agent knowledge; with `force` it replaces the stored copy of an already indexed page, which cannot be undone, and every call starts a new crawl."),
   "ethora-source-site-crawl-wait": REPLACE_JOB("Same as the crawl tool, then waits for the job: fetches an external website and stores its pages; with `force` it replaces the stored copy of an already indexed page, and every call starts a new crawl."),
-  "ethora-source-site-crawl-cancel": TOGGLE("Stops a running crawl job; stopping twice changes nothing more and nothing is deleted."),
+  "ethora-source-site-crawl-cancel": A(false, true, true, true, "Stops a running crawl job and discards the pages it had not finished storing, which cannot be resumed (a new crawl can be started); cancelling twice changes nothing more."),
   "ethora-source-site-reindex": REPLACE_JOB("Re-fetches one indexed URL from its website and replaces its stored content, so the previous copy is gone; every call fetches again."),
   "ethora-source-site-reindex-wait": REPLACE_JOB("Re-fetches one indexed URL, replaces its stored content and waits for the result; every call fetches again."),
   "ethora-source-site-refresh": REPLACE_JOB("Re-crawls a whole site or named pages now and replaces their stored content; every call fetches again."),

src/toolGroups.ts

@@ -59,7 +59,7 @@ export const TOOL_GROUPS: Record<string, { summary: string; tools: string[] }> =
   rooms: {
     summary: "Delete rooms, broadcast to many rooms, search messages, read message context and unread counts.",
     tools: [
-      "ethora-chat-delete", "ethora-broadcast-send", "ethora-broadcast-job-start", "ethora-broadcast-job-wait",
+      "ethora-chat-delete", "ethora-broadcast-send", "ethora-broadcast-job-get", "ethora-broadcast-job-wait",
       "ethora-message-search", "ethora-message-context", "ethora-chat-unread-counts",
     ],
   },
@@ -86,7 +86,7 @@ export const TOOL_GROUPS: Record<string, { summary: string; tools: string[] }> =
   },
   "users-files": {
     summary: "Batch-create users and upload, fetch or delete files.",
-    tools: ["ethora-user-batch-create", "ethora-user-batch-job-start", "ethora-user-batch-job-wait", "ethora-file-upload", "ethora-file-get", "ethora-file-delete"],
+    tools: ["ethora-user-batch-create", "ethora-user-batch-job-get", "ethora-user-batch-job-wait", "ethora-file-upload", "ethora-file-get", "ethora-file-delete"],
   },
   "legacy-bot": {
     summary: "The per-app bot of apps created in the dashboard before the agents framework, and the pre-v2 document tools. Prefer the agents and sources tools for anything new.",
@@ -126,8 +126,8 @@ export function groupOf(name: string): string | undefined {
 const VARIANT_NOTES: Record<string, string> = {
   "ethora-source-site-crawl": "Async variant: returns a job id to poll. Prefer `ethora-source-site-crawl-wait` unless the crawl is expected to exceed its wait budget.",
   "ethora-source-site-reindex": "Async variant: returns a job id to poll. Prefer `ethora-source-site-reindex-wait` unless the job is expected to exceed its wait budget.",
-  "ethora-broadcast-job-start": "Async variant of `ethora-broadcast-send`; pair with `ethora-broadcast-job-wait`.",
-  "ethora-user-batch-job-start": "Async variant of `ethora-user-batch-create`; pair with `ethora-user-batch-job-wait`.",
+  "ethora-broadcast-job-get": "Read-only: the current state of a broadcast job started by `ethora-broadcast-send`; `ethora-broadcast-job-wait` polls it to completion.",
+  "ethora-user-batch-job-get": "Read-only: the current state of a users batch job started by `ethora-user-batch-create`; `ethora-user-batch-job-wait` polls it to completion.",
   "ethora-source-doc-upload-legacy": "Legacy pre-v2 upload for the per-app bot. For agents use `ethora-source-doc-upload`.",
   "ethora-source-doc-delete-legacy": "Legacy pre-v2 delete for the per-app bot. For agents use `ethora-source-doc-delete`.",
   "ethora.b2b.auth.use": "Legacy dotted name kept for old integrations; use `ethora-auth-mode-set`.",

src/toolNames.ts

@@ -43,7 +43,8 @@ export const TOOL_RENAMES: Record<string, string> = {
   "ethora-chats-message-v2": "ethora-message-send",
   "ethora-chats-history-v2": "ethora-chat-history",
   "ethora-chats-broadcast-v2": "ethora-broadcast-send",
-  "ethora-chats-broadcast-job-v2": "ethora-broadcast-job-start",
+  "ethora-chats-broadcast-job-v2": "ethora-broadcast-job-get",
+  "ethora-broadcast-job-start": "ethora-broadcast-job-get",
   "ethora-wait-broadcast-job-v2": "ethora-broadcast-job-wait",
   "ethora-messages-search-v2": "ethora-message-search",
   "ethora-messages-context-v2": "ethora-message-context",
@@ -96,7 +97,8 @@ export const TOOL_RENAMES: Record<string, string> = {
   "ethora-sources-docs-delete-v2": "ethora-source-doc-delete",
   // users and files
   "ethora-users-batch-create-v2": "ethora-user-batch-create",
-  "ethora-users-batch-job-v2": "ethora-user-batch-job-start",
+  "ethora-users-batch-job-v2": "ethora-user-batch-job-get",
+  "ethora-user-batch-job-start": "ethora-user-batch-job-get",
   "ethora-wait-users-batch-job-v2": "ethora-user-batch-job-wait",
   "ethora-files-upload-v2": "ethora-file-upload",
   "ethora-files-get-v2": "ethora-file-get",

src/toolTitles.ts

@@ -16,7 +16,7 @@ export const TOOL_TITLES: Record<string, string> = {
   "ethora-auth-mode-set": "Set Auth Mode",
   "ethora-app-select": "Select App",
   "ethora-broadcast-send": "Broadcast Message",
-  "ethora-broadcast-job-start": "Get Broadcast Job",
+  "ethora-broadcast-job-get": "Get Broadcast Job",
   "ethora-broadcast-job-wait": "Wait for Broadcast Job",
   "ethora-file-upload": "Upload File",
   "ethora-file-get": "Get File",
@@ -40,7 +40,7 @@ export const TOOL_TITLES: Record<string, string> = {
   "ethora-source-doc-tags-update": "Update Knowledge Document Tags",
   "ethora-source-doc-delete": "Delete Knowledge Document",
   "ethora-user-batch-create": "Batch Create Users",
-  "ethora-user-batch-job-start": "Get Users Batch Job",
+  "ethora-user-batch-job-get": "Get Users Batch Job",
   "ethora-user-batch-job-wait": "Wait for Users Batch Job",
   "ethora-app-token-list": "List App Tokens",
   "ethora-app-token-create": "Create App Token",