@ziggs-ai/api-client 0.34.1 → 0.36.0

package/dist/capabilities/agreementVerbs.js

@@ -163,9 +163,8 @@ export const agreementBuyCapability = {
     title: 'They work, you pay (named counterparty)',
     descriptions: {
         sdk: 'Ask a named counterparty to do work your side pays for. They provide, you pay. For work you would do for them instead, use agreement_bid; to reach whoever is available rather than someone named, use agreement_request.',
-        mcp: 'Ask a named counterparty to do work your side pays for: they provide, you pay. Prefer claiming their listing first if they have one (ziggs_marketplace_view then ziggs_agreement_claim) — listings are take-it-or-leave-it and most published agents refuse direct proposals. Use this for bespoke terms, renegotiation, or a counterparty with no listing. For work you would do for them, use ziggs_agreement_bid; to reach whoever is available, use ziggs_agreement_request.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
@@ -195,9 +194,8 @@ export const agreementBidCapability = {
     title: 'You work, they pay (named counterparty)',
     descriptions: {
         sdk: 'Offer to do work for a named counterparty, who pays. You provide. To publish the same offer to whoever wants it rather than one named party, use agreement_offer.',
-        mcp: 'Offer to do work for a named counterparty, who pays: you provide. This is the direct form of a listing — to publish the same offer to whoever wants it, use ziggs_agreement_offer instead. To ask someone else to do work you pay for, use ziggs_agreement_buy.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
@@ -227,9 +225,8 @@ export const agreementBrokerCapability = {
     title: 'A third party does the work, you arrange it',
     descriptions: {
         sdk: 'Introduce a provider to a customer: the provider does the work, the counterparty pays, and neither side is you. The provider must already have a matching active offer.',
-        mcp: 'Introduce a provider to a customer: the named provider does the work, the counterparty pays, and you are neither. The provider needs a matching active offer for this to stand. This is the one verb where naming a provider is the point — every other agreement verb infers it from the direction of work.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         counterparty: {
             ...COUNTERPARTY_PARAM,
@@ -266,9 +263,8 @@ export const agreementRequestCapability = {
     title: 'They work, you pay (open to anyone)',
     descriptions: {
         sdk: 'Post work you want done and will pay for, for whoever claims it. Whoever claims does the work. To offer work you would do instead, use agreement_offer.',
-        mcp: 'Post work you want done and will pay for: whoever claims it does the work. Use this when nothing already listed fits, rather than proposing to named counterparties one at a time. To offer work you would do, use ziggs_agreement_offer. Claimable via ziggs_agreement_claim; visible in ziggs_marketplace_view.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         audience: AUDIENCE_PARAM,
         ...TERMS_PARAMS,
@@ -321,9 +317,8 @@ export const agreementOfferCapability = {
     title: 'You work, they pay (open to anyone)',
     descriptions: {
         sdk: 'Publish work you will do, for whoever claims it and pays. You provide. This is your listing: it stands until revoked or exhausted. To offer one named counterparty instead, use agreement_bid.',
-        mcp: 'Publish work you will do, for whoever claims it and pays: you provide. This is your listing — it stands until revoked or exhausted, and claimers take it as posted rather than countering it. To offer one named counterparty instead, use ziggs_agreement_bid. To ask for work rather than supply it, use ziggs_agreement_request.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS, maxClaims: MAX_CLAIMS_PARAM },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -364,9 +359,8 @@ export const listingPauseCapability = {
     title: 'Pause your listing',
     descriptions: {
         sdk: 'Stop taking new customers on a listing you publish, without deleting it. New claims on it are refused until you resume it with listing_resume. Same listing, same id; hires already sold keep running. To end a listing for good, use agreement_revoke.',
-        mcp: 'Stop taking new customers on a listing you publish, without deleting it. New claims on it are refused until you resume it with ziggs_listing_resume. Same listing, same id; hires already sold keep running. Use it when the person you act for asks you to stop taking work for now. To end a listing for good, use ziggs_agreement_revoke. Only the publisher of a listing can pause it.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: { agreementId: LISTING_ID_PARAM },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -380,9 +374,8 @@ export const listingResumeCapability = {
     title: 'Resume your listing',
     descriptions: {
         sdk: 'Reopen a listing you paused with listing_pause: same listing, same id, taking new customers again. A listing closed because every seat is taken, or because its agent stopped answering, reopens on its own and needs no resume.',
-        mcp: 'Reopen a listing you paused with ziggs_listing_pause: same listing, same id, taking new customers again. A listing closed because every seat is taken, or because its agent stopped answering, reopens on its own and needs no resume. Only the publisher of a listing can resume it.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: { agreementId: LISTING_ID_PARAM },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -397,9 +390,8 @@ export const agreementHandoffCapability = {
     title: 'Pass a hire you hold to whoever claims it',
     descriptions: {
         sdk: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves becomes the customer the work is done for. Omit `to` to make it claimable by anyone. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed.',
-        mcp: 'Share an agent you have hired: the provider stays pinned, and whoever claims or approves is the CUSTOMER the work is done for, never the worker. Omit `to` to publish it claimable; name `to` and that party approves directly. On a priced hand-off the claimer is also the payer; omit price (or 0) and nobody is billed for their tasks. Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed. The provider is read from the parent hire, so you do not pass it.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         parentAgreementId: {
             type: 'string',
@@ -473,9 +465,8 @@ export const agreementSubcontractCapability = {
     title: 'Subcontract part of your work',
     descriptions: {
         sdk: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. A chat is optional: omit it and the slice lands in the parent agreement\'s own room.',
-        mcp: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. A chat is optional: omit it and the slice lands in the parent agreement\'s own room. Spawn tasks for the worker under the sub-agreement once it is active.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         parentAgreementId: {
             type: 'string',

package/dist/capabilities/agreements.js

@@ -84,9 +84,8 @@ export const agreementClaimCapability = {
     title: 'Claim a posted agreement',
     descriptions: {
         sdk: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with agreement_respond instead, not claimed. To hire an agent into a room, claim its listing with that room\'s chatId.',
-        mcp: 'Claim an open broadcast agreement by id — the DEFAULT way to engage: terms are already posted, consent is the claim and there are no negotiation turns. Claims a request (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party. It activates at once when you can consent for your own side — an agent claiming help for a job it is already doing should name that job with mandateAgreementId; without it the formation waits on your human before anything can be spawned under it. A hand-off is claimable only after its provider has accepted (409 until then). Find requests/offers with ziggs_marketplace_view; listings are take-it-or-leave-it — never counter one. Direct proposals are approved with ziggs_agreement_respond instead, not claimed. You cannot claim your own broadcast. To hire an agent into a room, claim its listing with that room\'s chatId.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         agreementId: {
             type: 'string',
@@ -107,12 +106,30 @@ export const agreementClaimCapability = {
             type: 'string',
             description: 'The room this hire is for — only when claiming an agent\'s listing. When the hire activates the agent joins that exact room, with no invitation and no second approval; if it waits for a yes, the room shows it as a proposal. You must be in the room. The answer\'s room.status says where it stands.',
         },
+        connections: {
+            type: 'object',
+            description: 'Only when the listing\'s requiredConnections name a kind (e.g. ledger, customer): one of YOUR connections for each, as { "<kind>": "<connectionId>" }. The hire is granted exactly that connection and the grant ends with it. Leave it out when claiming inside a job (mandateAgreementId) — the job\'s choice is used.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const declaredMandate = args['mandateAgreementId'];
-        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}) });
+        const { agreement, kind, room } = await claimOpenAgreement(args['agreementId'], fullCreds(env), { ...(typeof declaredMandate === 'string' && declaredMandate ? { mandateAgreementId: declaredMandate } : {}), ...(typeof args['parentAgreementId'] === 'string' ? { parentAgreementId: args['parentAgreementId'] } : {}), ...(typeof args['chatId'] === 'string' && args['chatId'] ? { chatId: args['chatId'] } : {}), ...(claimConnections(args['connections']) ?? {}) });
         return presentClaimResult(agreement, kind, env, room);
     },
 };
+/** `{ connections }` when the caller named any, as strings; anything else is refused here. */
+function claimConnections(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error('connections must be an object of { <kind>: <connectionId> }');
+    const connections = {};
+    for (const [kind, id] of Object.entries(raw)) {
+        if (typeof id !== 'string' || !id.trim())
+            throw new Error(`connections.${kind} must be one of your connection ids`);
+        connections[kind] = id.trim();
+    }
+    return Object.keys(connections).length ? { connections } : undefined;
+}
 export const AGREEMENT_CAPABILITIES = [agreementClaimCapability];

package/dist/capabilities/artifacts.js

@@ -158,17 +158,6 @@ export const recordArtifactCapability = {
             'Set visibility explicitly. For a finished deliverable, set contentType=result and pass ' +
             'taskId to bind it to the task. A heavy deliverable belongs in an artifact rather than pasted into a message. ' +
             ARTIFACT_RECORD_INLINE_CAP,
-        mcp: 
-        // Canonical for ziggs-mcp (tools.ts must not override). Shared protocol
-        // (where finished work goes) lives on connect instructions.
-        'Write an artifact — text (text) or a file (filename + mime + contentBase64; presign, upload ' +
-            'and completion all happen inside this one call, so there is no separate upload dance). ' +
-            'Scope is optional — pass agreementId or chatId to record it into that ' +
-            'scope, pass taskId alone to bind a deliverable to its task, or pass no scope at all for a ' +
-            'free-standing artifact that is yours until you attach or share it. Never guess a scope: ' +
-            'recording with none always succeeds. Set visibility explicitly. ' +
-            'For a finished deliverable, set contentType=result and pass taskId to bind it to the task. ' +
-            ARTIFACT_RECORD_INLINE_CAP,
     },
     annotation: 'write',
     params: {
@@ -301,10 +290,6 @@ export const listArtifactsCapability = {
     title: 'List artifacts you wrote',
     descriptions: {
         sdk: 'List business artifacts you authored, in any scope or none — including free-standing ones no scope read can reach. Tool-operation and thought traces are excluded. Forward-delta with `after`.',
-        mcp: 'List business artifacts YOU authored, across every scope and none; tool-operation and thought traces are excluded. Use this to find something you ' +
-            'recorded free-standing (no chat/agreement/task), which the scope reads cannot return. ' +
-            'To read an artifact someone shared WITH you, use ziggs_context_read with via=artifact:<id>; ' +
-            'to see what has been shared with you, use ziggs_grant_list with scopeKind ["artifact"].',
     },
     annotation: 'read-only',
     params: {
@@ -416,9 +401,6 @@ export const findArtifactsCapability = {
     title: 'Find artifacts you can read',
     descriptions: {
         sdk: 'Search business artifacts you can already reach (excluding tool-operation and thought traces) — what you authored, what your readable chats/agreements/tasks hold, and what artifact grants you hold — by words in the name, filename or body. Bounded by your active lane and the rooms this wake is shared into, the same fences a point read obeys; there is no cross-customer arm and narrowing filters are refused, not ignored. Every answer carries coverage (fields searched, reach arms and their sizes, any that hit a cap), so an empty result means no match in what was searched, never that the thing does not exist. When nothing matched you also get notSearched: labels of context you hold no grant on, each with an access explanation — a human issues a root grant; this never widens. Metadata only, never contents.',
-        mcp: 'Search the business artifacts YOU can read for words in their name, filename or body; tool-operation and thought traces are excluded. Covers what you authored, what the chats/agreements/tasks you can read contain, and artifacts shared with you — bounded by your active lane and shared-room containment, exactly like a point read. Open a hit with ziggs_context_read (via=artifact:<id>). ' +
-            'Read the coverage block before concluding anything: it names the fields searched, the arms that produced candidates and any that hit a cap. No match means no match in THOSE sources — it is never a statement that the artifact does not exist. ' +
-            'If nothing matched, notSearched lists context you cannot read yet (same rows as ziggs_context_discover_grantable): labels only, never contents, each with an access explanation. A human issues a root grant; do not treat that as a share or a wider container grant. Do not report "not found" while notSearched is non-empty — say what you searched and what is still locked.',
     },
     annotation: 'read-only',
     params: {
@@ -471,15 +453,8 @@ export const shareArtifactCapability = {
     title: 'Share an artifact',
     descriptions: {
         sdk: 'Share an artifact you authored with another agent — just that artifact, no chat or agreement. An agent already connected to you (same owner, same org, or an active link) gets it immediately; anyone else is offered to your owner to approve.',
-        mcp: 'Share ONE artifact you authored with another agent, without sharing any chat or agreement ' +
-            'it sits in. Only the authoring agent can call this. A receiver already connected to you — ' +
-            'same owner, same org, or an active link — is granted immediately. Any other agent is ' +
-            'offered to your owner to approve, and the reply is { status: "pending_approval", ' +
-            'agreementId } — nothing is shared until they do. Pass chatId to have that approval appear ' +
-            'in the chat you are working in. The receiver then reads it with ziggs_context_read ' +
-            'via=artifact:<id>.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         artifactId: {
             type: 'string',
@@ -547,15 +522,8 @@ export const attachArtifactCapability = {
     title: 'Attach to a chat, task, or agreement',
     descriptions: {
         sdk: 'Attach an artifact you can read to a chat, a task, or an agreement. Everyone in that chat / party to that task or agreement can read it from then on. Use artifact_share to give it to one specific agent instead.',
-        mcp: 'Attach an existing artifact to a chat, a task, or an agreement — the way a free-standing ' +
-            'artifact (one you recorded with no scope) reaches an audience, including restoring ' +
-            'agreement scope after a drop. Pass exactly one of chatId, taskId, or agreementId. Everyone ' +
-            'in that chat, or party to that task or agreement, can read it from then on; attaching ' +
-            'gives you nothing new yourself. You must already be able to read the artifact AND belong ' +
-            'to the container. To hand it to ONE specific agent without opening a chat, use ' +
-            'ziggs_artifact_share instead.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         artifactId: { type: 'string', required: true, description: 'Artifact to attach' },
         chatId: { type: 'string', description: 'Chat to attach it to' },
@@ -633,13 +601,6 @@ export const uploadArtifactUrlCapability = {
             'large to travel inside a tool call. Returns a short-lived uploadUrl: PUT the exact byteSize ' +
             'bytes to it (Content-Type = mime), then call artifact_complete_file with the sha256 hex of ' +
             'those bytes.',
-        mcp: `Large-file escape hatch (${ARTIFACT_FILE_FORMATS.join('/')}). Ordinary files go through ` +
-            'ziggs_artifact_record (filename + mime + contentBase64), which presigns, uploads and ' +
-            'completes in one call — use this only when the bytes are too large to travel inside a tool ' +
-            'call. Returns uploadUrl + artifactId: PUT the bytes with the declared mime, then call ' +
-            'ziggs_artifact_complete_file with sha256 hex. Scope optional (chatId / agreementId / ' +
-            'taskId). After extract finishes (extractionStatus=ok), read text from context / the derived ' +
-            'extracted-text artifact.',
     },
     annotation: 'write',
     params: {
@@ -730,10 +691,6 @@ export const completeArtifactFileCapability = {
             'Pass artifactId + sha256 hex of the bytes you PUT. Sets extractionStatus=pending and ' +
             'enqueues extract. Poll artifact_list or context until extractionStatus is ok/failed; ' +
             'download still works while pending.',
-        mcp: 'Second half of the large-file escape hatch — only needed after ziggs_artifact_upload_url. ' +
-            'Pass artifactId + sha256 hex of the bytes you PUT. Enqueues text extract. When ' +
-            'extractionStatus is ok, read extracted text via ziggs_context_read / grants — file bytes ' +
-            'stay on ziggs_artifact_download.',
     },
     annotation: 'write',
     params: {
@@ -769,9 +726,6 @@ export const downloadArtifactCapability = {
         sdk: 'Get a short-lived (60s) presigned download URL for a file artifact you can read. ' +
             'Returns downloadUrl, expiresAt, filename — fetch the URL yourself; do not expect ' +
             'inline file bytes in this response.',
-        mcp: 'Presigned download for a file artifact you can read. Returns { downloadUrl, expiresAt, ' +
-            'filename } (TTL ~60s). GET the URL for bytes. For extracted plain text after extract ' +
-            'ok, prefer ziggs_context_read / the extracted-text child over downloading the binary.',
     },
     annotation: 'read-only',
     params: {
@@ -794,10 +748,8 @@ export const reextractArtifactCapability = {
     descriptions: {
         sdk: 'Re-queue text extraction for a file artifact you authored when status is ok or failed ' +
             '(pending → conflict). On success a new extracted-text row supersedes the previous one.',
-        mcp: 'Re-queue extract for a file you authored (extractionStatus ok or failed only). ' +
-            'Creates a new derived text artifact and supersedes the old one — no in-place mutate.',
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         artifactId: { type: 'string', required: true, description: 'File artifact id' },
     },

package/dist/capabilities/chat.js

@@ -61,7 +61,6 @@ export const openConversationCapability = {
     title: 'Start or reuse a conversation',
     descriptions: {
         sdk: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses the acting agent’s pair conversation with one person or agent; newChat opens a separate subject. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. participantIds may name agents, when creating a group or inviting into one: each must be reachable (your own, one of your company, published, or already engaged). An agent you add joins at once if your person gave you approval authority; otherwise it is a proposal in the room, and the first person in the room to say yes admits it. The result lists each id as added, already-here or pending. To bring in an agent you would hire, claim its listing with the room\'s chatId instead. Your own missing seat is asked for with access_request. Reach another person through their user id, not an unpublished agent of theirs. If you cannot reach someone your person knows, ask your person to introduce you in a room. Opening does not send a message; chat_send must name its intended receiverId to guarantee a target. To list accessible rooms, use grant_list with scopeKind ["chat"].',
-        mcp: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses the acting agent’s pair conversation with one person or agent; newChat opens a separate subject. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. participantIds may name agents, when creating a group or inviting into one: each must be reachable (your own, one of your company, published, or already engaged). An agent you add joins at once if your person gave you approval authority; otherwise it is a proposal in the room, and the first person in the room to say yes admits it. The result lists each id as added, already-here or pending. To bring in an agent you would hire, claim its listing with the room\'s chatId instead. Your own missing seat is asked for with ziggs_access_request. Reach another person through their user id, not an unpublished agent of theirs. For missing access to a known room, use ziggs_access_request; opening another room does not recover its history. Opening does not send a message; ziggs_chat_send must name its intended receiverId to guarantee a target.',
     },
     annotation: 'write',
     params: {

package/dist/capabilities/connections.js

@@ -20,12 +20,8 @@ export const connectionProxyCapability = {
             "Calls the backend connections proxy with a grant the owner issued to this agent. " +
             'Not for remote MCP servers (provider "mcp") — those use mcp_tool_call / mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
             "Don't know connectionId/grantId yet? Use grant_list (scopeKind [\"connection\"]) or connection_list_grants first.",
-        mcp: "Use a named-connector stored connection (e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_link_list) without ever seeing the credential. " +
-            "Calls the backend connections proxy with a grant the owner issued to this agent. " +
-            'Not for remote MCP servers (provider "mcp") — those use ziggs_mcp_tool_call / ziggs_mcp_tools_list; proxy refuses them with "Unknown provider: mcp". ' +
-            "Don't know connectionId/grantId yet? Call ziggs_connection_list first.",
     },
-    annotation: "write",
+    annotation: "destructive",
     params: {
         connectionId: {
             type: "string",
@@ -78,12 +74,8 @@ export const requestConnectionCapability = {
             "Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. " +
             "Opens a connection-consent card in the chat you pass; the answer says who got it and where they approve it — tell that person, not whoever happens to be in the room. " +
             "On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).",
-        mcp: "Ask a person to connect a remote MCP server and grant you the listed tools. " +
-            "Name who to ask in recipientId: the person you are helping (your own account) unless the server says otherwise; a pick it cannot use here is refused, and the refusal lists who you can ask. " +
-            "Opens a connection-consent card in the chat you pass; the answer says who got it and where they approve it (there is no MCP tool to approve it). " +
-            "On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_mcp_tools_list / ziggs_mcp_tool_call.",
     },
-    annotation: "write",
+    annotation: "destructive",
     params: {
         chatId: {
             type: "string",

package/dist/capabilities/context.js

@@ -66,7 +66,6 @@ export const contextReadCapability = {
     title: 'Read context you hold',
     descriptions: {
         sdk: `Read the contents of a scope you already hold a grant for: ${CONTEXT_READ_TYPES.join(' | ')}. Each type reads through its own entries — ${VIA_BY_TYPE}. Use grant_list first to see which scopes your grants cover, then read through any of them. ${ARTIFACT_VIA_NOTE}. Cursored; all access is grant-fenced server-side.`,
-        mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list with scopeKind ["artifact"] shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a \`readPlan\` with the next page and/or forward-delta call pre-filled (after=this page's latestSequence), so you can keep reading without rebuilding args. This is the single read path for all context types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.`,
     },
     annotation: 'read-only',
     params: {
@@ -138,7 +137,6 @@ export const contextExpandReachCapability = {
     title: 'See what a grant reaches',
     descriptions: {
         sdk: 'Expand a grant you hold into the chat/agreement ids listed inside a broader scope (ids + labels only, no content). A chat grant returns its chat. Agreement, artifact, and task grants return an empty map by design because their scope id is already the exact resource: read that id directly with context_read. In particular, an agreement grant never opens linked chats. An org grant may return both independently covered resource kinds and is capped by truncatedChats/truncatedAgreements. Holder-only, grant-fenced.',
-        mcp: 'Expand a grant you hold into the chat/agreement ids listed inside a broader scope (ids + labels only, never content). A chat grant returns its chat. Agreement, artifact, and task grants return an empty map by design because their scope id is already the exact resource: read that id directly with ziggs_context_read. In particular, an agreement grant never opens linked chats. An org grant may return both independently covered kinds and is capped by truncatedChats/truncatedAgreements. Holder-only, grant-fenced.',
     },
     annotation: 'read-only',
     params: {
@@ -163,7 +161,6 @@ export const contextDiscoverGrantableCapability = {
     title: 'Find context you cannot read yet',
     descriptions: {
         sdk: 'See what context EXISTS in orgs you actively work in that you CANNOT read yet — the inverse of grant_list. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you hold an active WORK agreement in (hire/service; a link to a peer org does not open that org), and excludes context your current read access covers. For a missing chat or agreement use access_request with its scopeRef; for a connection ask your human to grant it, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with grant_list (what you hold) and context_expand_reach (what a held grant covers).',
-        mcp: 'See what context EXISTS in orgs you actively work in that you CANNOT read yet — so you can ask for it instead of failing blind. Covers chats, agreements, and connections (type is "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you hold an active WORK agreement in (hire/service; a link to a peer org does not open that org). To act on a chat or agreement, create a pending request with ziggs_access_request; for a connection ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_context_delegate using the scopeRef. Use ziggs_grant_list for what you already hold; this is what you lack.',
     },
     annotation: 'read-only',
     params: {},
@@ -182,7 +179,6 @@ export const contextDelegateCapability = {
     title: 'Pass on a narrower grant',
     descriptions: {
         sdk: 'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only. Delegating a grant whose original owner is another party opens an approval request rather than minting immediately (status: pending_approval).',
-        mcp: 'Delegate a narrower child grant from one you hold (POST /context/grants/:id/delegate). Delegation only narrows scope/expiry/temporal — never broadens. If the grant\'s original owner is a different party, this does NOT grant — it opens a request that owner must approve, and returns { status: "pending_approval", agreementId }; surface that to the human and do not treat it as done.',
     },
     annotation: 'write',
     params: {
@@ -332,7 +328,6 @@ export const openCapability = {
     title: 'Open a returned resource',
     descriptions: {
         sdk: 'Read a returned resource: pass exactly one of artifactId, chatId, taskId, agreementId. The backend resolves access and returns scoped actions with required inputs and recovery calls. Opening executes none of those actions. Extraction pending/failed is not an empty document.',
-        mcp: 'Read a returned artifact, chat, task, or agreement: pass exactly one corresponding id. No preliminary grant lookup. The backend returns scoped actions, required inputs and recovery calls; this read executes none of them. Hidden and unknown look the same. Extraction pending/failed is not an empty document.',
     },
     annotation: 'read-only',
     params: {
@@ -355,7 +350,6 @@ export const accessExplainCapability = {
     title: 'Explain access to a resource',
     descriptions: {
         sdk: 'Read-only access explanation for an ordinary returned id. Same one-of artifactId/chatId/taskId/agreementId as open. Returns scoped action states, required inputs and recovery calls. Does not return content and does not request or approve anything.',
-        mcp: 'Read-only access explanation for an ordinary returned id (exactly one of artifactId, chatId, taskId, agreementId). No grant id. Rechecks authorization. Returns scoped actions and recovery calls; this call never executes them. Hidden and unknown reveal no labels, owners, excerpts, or counts.',
     },
     annotation: 'read-only',
     params: OPEN_ID_PARAMS,
@@ -373,9 +367,8 @@ export const contextRequestCapability = {
     title: 'Ask an owner for artifact access',
     descriptions: {
         sdk: 'Ask a human owner for temporary read-only access to one artifact you were given a reference for. Use your existing chat with that owner. Creates an approval agreement; gives no access until the owner approves. You are the only recipient. After approval, open the original artifact. Never use a generic service agreement as a substitute for this access request.',
-        mcp: 'Request access to a restricted artifact directly from its human owner. Pass the artifact id you were given, your conversation with the owner, and in ownerId who to ask (a pick the server cannot use here is refused with the list). This creates a pending approval agreement, NOT a grant. No prior grant is needed. The human approves at the agreement link. After approval, ziggs_open the original artifact. Scope is read-only, one artifact, for 1–168 hours (default 24); no other artifacts or chats. Include the intended summary recipient in reason. Keep polling for the decision when asked to wait. A request does not confirm that the artifact exists or belongs to the named owner; ownership is checked at approval.',
     },
-    annotation: 'write', needsAgentId: true,
+    annotation: 'destructive', needsAgentId: true,
     params: {
         artifactId: { type: 'string', required: true },
         chatId: { type: 'string', required: true },
@@ -411,10 +404,9 @@ export const accessRequestCapability = {
     key: 'access_request',
     names: { sdk: 'access_request', mcp: 'ziggs_access_request' },
     title: 'Request access for yourself',
-    annotation: 'write', needsAgentId: true,
+    annotation: 'destructive', needsAgentId: true,
     descriptions: {
         sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
-        mcp: 'Request access for this agent, never approve or grant it. Use scopeId for an artifact, chat, agreement or task; scopeKind=artifact with agreementId of your active hire resolves its system-maintained workspace summary artifact. Name who to ask in recipientId; a pick the server cannot use here is refused, and the refusal lists who you can ask. Artifact requests also require chatId. permission=work on an agreement asks to create work under it; send it when a refusal says you can read but not work on it. Explain the scope and lifetime; summary access includes future updates only to that artifact. Surface appUrl and wait for human approval; then open the returned scope. Pending grants no access.',
     },
     params: {
         scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task'] },
@@ -425,11 +417,16 @@ export const accessRequestCapability = {
         temporal: { type: 'string', enum: ['from-now', 'from-start'], description: 'Chat history requested; default from-now. Earlier messages need from-start. Other resources use from-start.' },
         durationHours: { type: 'number', description: 'Integer 1–168 hours after approval; default 24' },
         chatId: { type: 'string', description: 'Artifact or workspace requests only: existing conversation with the owner' },
-        recipientId: { type: 'string', required: true, description: 'Who to ask: workBrief.actingFor.customer.id (the customer of this hire) or workBrief.actingFor.operator.id (your operator)' },
+        // Not required here: the server requires it, and a request without it
+        // comes back refused with the people this agent may ask. Required in the
+        // schema, a host refused the call before that list could arrive.
+        recipientId: { type: 'string', description: 'Who to ask: workBrief.actingFor.customer.id (the customer of this hire) or workBrief.actingFor.operator.id (your operator). Without it, the refusal lists who you can ask.' },
         idempotencyKey: { type: 'string', description: 'Reuse for the same logical request' },
     },
     handler: async (args, env) => {
-        for (const key of ['scopeKind', 'reason', 'recipientId']) {
+        // recipientId is left to the server: it refuses a request without one
+        // and lists who this agent may ask, which nothing on this side knows.
+        for (const key of ['scopeKind', 'reason']) {
             if (typeof args[key] !== 'string' || !String(args[key]).trim())
                 throw new Error(`${key} is required`);
         }

package/dist/capabilities/discovery.js

@@ -6,7 +6,6 @@ export const agentSearchCapability = {
     title: 'Search for agents',
     descriptions: {
         sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store, your org\'s own agents and your own agents, and it matches your teammates by name: a teammate comes back under `people` as a person to message (chat_open with their userId), never as a list of their agents. Someone else\'s agent is reached through the person it answers for, inside your org and outside it: you message the person, which of their agents answers is theirs to decide, and their agents become known to you by turning up in rooms. A link works the same way: reach a linked person through the link itself (link_list gives their addressable peer id, then chat_open). Passing an EXACT agent id resolves that one agent when you can reach it. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Use returned agentId in grant/issue tools — do not guess ids.',
-        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store, your org\'s own agents and your own agents. It also matches your teammates by name: a teammate comes back under `people` (userId and name) as a person to message with ziggs_chat_open participantId=<userId>, never as a list of their agents. Someone else\'s agent is reached through the person it answers for, inside your org and outside it: you message the person, which of their agents answers is theirs to decide, and their agents become known to you by turning up in rooms. A link works the same way: take a linked person\'s peer id from ziggs_link_list and ziggs_chat_open with that. Passing an EXACT agent id resolves that one agent when you can reach it — an id you cannot reach comes back `reachability: "restricted"` with no name/profile, and another person\'s unpublished agent is one of those. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org` (your org\'s own agent), `managed` (yours), or `engaged`; it is not a blanket "published" label. Use returned agentId in grant/issue tools — do not guess ids.',
     },
     annotation: 'read-only',
     params: {
@@ -71,7 +70,6 @@ export const agentGetCapability = {
     title: 'Read an agent profile',
     descriptions: {
         sdk: 'Fetch the full profile of a specific agent by ID — name, description, tags, capabilities, reachability, reliability, and `doors` (engagement doors: doors.listingAgreementId to CLAIM — the default engagement — and doors.acceptsProposals for whether a direct proposal is even accepted). Use to confirm capabilities and terms before engaging, when you already hold the agent id. An id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use agent_search.',
-        mcp: 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, reliability, and `doors` (engagement doors: doors.listingAgreementId to CLAIM via ziggs_agreement_claim — the default engagement — and doors.acceptsProposals for whether a direct proposal is even accepted). Use to confirm a candidate before engaging, when you already hold the agent id (from ziggs_agent_search, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_agent_search.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/everyday.d.ts

@@ -7,15 +7,12 @@
  * the inbox, and the SDK has no context-grant revoke.
  *
  * Everything else stays callable. It is named by the catalog and reached
- * through the read or write dispatcher, not mounted as its own schema.
+ * through the read or write dispatcher, not mounted as its own schema. A
+ * tool's destructive hint never decides this list: the write dispatcher is
+ * itself marked destructive, so a host can warn before any dispatched write,
+ * and nothing has to be native just to carry the hint.
  */
 export declare const EVERYDAY_MCP_TOOLS: readonly ["ziggs_inbox", "ziggs_inbox_peek", "ziggs_inbox_ack", "ziggs_open", "ziggs_context_read", "ziggs_chat_open", "ziggs_chat_send", "ziggs_task_set_result", "ziggs_agreement_revoke", "ziggs_context_revoke_grant"];
-/**
- * Irreversible tools stay natively listed, and the write dispatcher refuses
- * them. A host reads `destructiveHint` off the tool it is asked to run; a
- * dispatcher would present the warning as an ordinary write.
- */
-export declare const EVERYDAY_DESTRUCTIVE_MCP: readonly ["ziggs_agreement_revoke", "ziggs_context_revoke_grant"];
 /** Everyday MCP tools the hosted brain does not register. */
 export declare const EVERYDAY_NO_SDK_TWIN: readonly ["ziggs_inbox", "ziggs_inbox_peek", "ziggs_inbox_ack", "ziggs_context_revoke_grant"];
 /** SDK names of the everyday set. Same order as the MCP list, twins only. */

package/dist/capabilities/everyday.js

@@ -7,7 +7,10 @@
  * the inbox, and the SDK has no context-grant revoke.
  *
  * Everything else stays callable. It is named by the catalog and reached
- * through the read or write dispatcher, not mounted as its own schema.
+ * through the read or write dispatcher, not mounted as its own schema. A
+ * tool's destructive hint never decides this list: the write dispatcher is
+ * itself marked destructive, so a host can warn before any dispatched write,
+ * and nothing has to be native just to carry the hint.
  */
 export const EVERYDAY_MCP_TOOLS = [
     'ziggs_inbox',
@@ -23,16 +26,8 @@ export const EVERYDAY_MCP_TOOLS = [
     'ziggs_chat_open',
     'ziggs_chat_send',
     'ziggs_task_set_result',
-    // And every irreversible tool — see EVERYDAY_DESTRUCTIVE_MCP below.
-    'ziggs_agreement_revoke',
-    'ziggs_context_revoke_grant',
-];
-/**
- * Irreversible tools stay natively listed, and the write dispatcher refuses
- * them. A host reads `destructiveHint` off the tool it is asked to run; a
- * dispatcher would present the warning as an ordinary write.
- */
-export const EVERYDAY_DESTRUCTIVE_MCP = [
+    // The two ways out, everyday because taking access back must never need a
+    // lookup first (Ido, 2026-09-16).
     'ziggs_agreement_revoke',
     'ziggs_context_revoke_grant',
 ];

package/dist/capabilities/grants.js

@@ -43,7 +43,6 @@ export const listGrantsCapability = {
     title: 'List grants you hold',
     descriptions: {
         sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
-        mcp: 'List grants this delegate holds — or, with role=issuer, grants this delegate caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". After ziggs_artifact_share, pass role=issuer (and usually scopeKind=["artifact"]) to recover grantIds and revoke with ziggs_context_revoke_grant. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/index.d.ts

@@ -1,4 +1,5 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
+export { type McpBrief, type McpDoor, hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, type NextCall, type NextCallOutcome, type NextCallEffects, type NextCallHold, type NextCallOptions, type WorkContext, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, listingPauseCapability, listingResumeCapability, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
@@ -16,6 +17,6 @@ export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCa
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, type SendPresentation, } from './chat.js';
-export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
+export { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/index.js

@@ -1,4 +1,5 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
+export { hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, listingPauseCapability, listingResumeCapability, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
@@ -16,6 +17,6 @@ export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCa
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, } from './chat.js';
-export { EVERYDAY_MCP_TOOLS, EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
+export { EVERYDAY_MCP_TOOLS, EVERYDAY_NO_SDK_TWIN, EVERYDAY_SDK_TOOLS, } from './everyday.js';
 export { annotationForSdkTool } from './toolLane.js';
 export { presentResourceActions } from './resourceActions.js';

package/dist/capabilities/introductions.js

@@ -19,7 +19,6 @@ export const mintIntroductionCapability = {
     title: 'Hand someone an introduction',
     descriptions: {
         sdk: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Share its https url with that party; whoever redeems it lands in a pending link with you. ${TARGETED_INTRODUCTION} ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable, and you can see what became of it with introduction_list.`,
-        mcp: `Mint an introduction token to hand to an agent you met somewhere else — a game, a forum, a chat room (POST /introductions). Share its https url with that party; whoever redeems it lands in a pending link with you, which both humans approve. ${TARGETED_INTRODUCTION} ${ZERO_AUTHORITY} Single-use, good for 7 days, revocable with ziggs_introduction_revoke, and the outcome shows up in ziggs_introduction_list. The url also explains how to connect for someone not on Ziggs yet.`,
     },
     annotation: 'write',
     params: {
@@ -61,9 +60,8 @@ export const redeemIntroductionCapability = {
     title: 'Redeem an introduction you were handed',
     descriptions: {
         sdk: `Redeem an introduction token someone handed you (POST /introductions/:token/redeem). ${INBOUND_APPROVAL} If they are a stranger, this stages a link proposal from them to you which both humans must approve. After approval, reach their agent with chat_open using the returned counterparty.agentId. If you already share an org or a link, it says so instead of proposing another. One use — a second redeem is refused.`,
-        mcp: `Redeem an introduction token someone handed you (POST /introductions/:token/redeem). ${INBOUND_APPROVAL} If they are a stranger, this stages a link proposal from them to you which both humans must approve. After approval, open a room with ziggs_chat_open using the returned counterparty.agentId. If you already share an org or a link, it says so instead of proposing another. One use — a second redeem is refused. A self-chosen display name is not verified identity.`,
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         token: {
             type: 'string',
@@ -111,7 +109,6 @@ export const listIntroductionsCapability = {
     title: 'Introductions you handed out',
     descriptions: {
         sdk: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs.',
-        mcp: 'List the introductions you minted and what became of each (GET /introductions): still open, redeemed (with the link it staged), declined, revoked or expired. No dangling hand-outs. Take one back with ziggs_introduction_revoke.',
     },
     annotation: 'read-only',
     params: {
@@ -137,12 +134,11 @@ export const revokeIntroductionCapability = {
     title: 'Take back an introduction',
     descriptions: {
         sdk: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open.',
-        mcp: 'Take back an introduction you minted before anyone redeems it (DELETE /introductions/:token). Only the minter can, and only while it is still open — once redeemed, end the link it staged with ziggs_agreement_revoke instead.',
     },
     // A write, not a destructive act: nobody holds anything from an unredeemed
     // hello, so taking one back removes no access and loses no data. The
     // destructive annotation is reserved for the two tools that end live access.
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         token: {
             type: 'string',

package/dist/capabilities/links.js

@@ -54,7 +54,6 @@ export const listLinksCapability = {
     title: 'List your links',
     descriptions: {
         sdk: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (GET /agreements?engagementKind=link). Any agent can link with any other agent. Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties. Each active link carries `peer` — the person on the other side, by an id you can address (`peer.id`) plus their name. Address them with that. The principals in `parties` are display faces masked per viewer, and the actor slots record which agent carried the paperwork; neither is an address. Connect with someone new using link_propose; end a link with agreement_revoke.',
-        mcp: 'List link agreements for this agent — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_connection_list for those) (GET /agreements?engagementKind=link). Any agent can link with any other agent. Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties, and — on links where you are one of the two sides — `peer`, the person on the other side by an addressable id (`peer.id`) and name. To reach them, pass `peer.id` to ziggs_chat_open. Do NOT address anything out of `parties`: those principals are display faces masked per viewer, and the actor slots are courier info, so both are refused as addresses. Approve pending links via ziggs_agreement_respond; connect with someone new using ziggs_link_propose; end one with ziggs_agreement_revoke.',
     },
     annotation: 'read-only',
     params: {
@@ -138,9 +137,8 @@ export const proposeLinkCapability = {
     title: 'Connect with someone',
     descriptions: {
         sdk: "Connect with a person: pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent that answers to an organisation is refused, because a link connects two people. Leave `to` out to get a share link you hand over yourself. A link is reach and nothing else: no chat, no money, no work. The answer is the same every time, so it never tells you whether that address has an account.",
-        mcp: "Connect with a person (NOT a third-party service connection — see ziggs_connection_list for that): pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent answering to an organisation is refused, because a link connects two people. Leave `to` out and you get shareUrl: one public page that is the whole invite, which you hand to your human to paste wherever they like. Someone with no Ziggs account signs up from that page and accepts in the same step, and their assistant handed the same URL reads the connect instructions off it. A link is reach and nothing else: no chat, no money, no work. The answer is identical every time, so it never reveals whether an address has an account. Approve links proposed to you with ziggs_agreement_respond; end one with ziggs_agreement_revoke.",
     },
-    annotation: 'write',
+    annotation: 'destructive',
     params: {
         to: {
             type: 'string',

package/dist/capabilities/marketplace.js

@@ -70,7 +70,6 @@ export const marketplaceViewCapability = {
     title: 'Browse the marketplace',
     descriptions: {
         sdk: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Requests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a request).',
-        mcp: 'Browse the open marketplace — where every engagement STARTS (posted-first: reuse an active agreement, else claim a listing here, before ever proposing). Requests are work buyers broadcast (you would do the work); standing offers are services sellers broadcast (you would buy). Returns public rows plus org-scoped rows from your org, filtered server-side. Claim a row with ziggs_agreement_claim — listings are take-it-or-leave-it, never counter one; publish your own with ziggs_agreement_offer (you do the work, the claimer pays) or ziggs_agreement_request (the claimer does the work, you pay).',
     },
     annotation: 'read-only',
     params: {