@ziggs-ai/api-client 0.35.0 → 0.36.0

package/dist/capabilities/agreementVerbs.js

@@ -163,7 +163,6 @@ 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: 'destructive',
     params: {
@@ -195,7 +194,6 @@ 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: 'destructive',
     params: {
@@ -227,7 +225,6 @@ 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: 'destructive',
     params: {
@@ -266,7 +263,6 @@ 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: 'destructive',
     params: {
@@ -321,7 +317,6 @@ 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: 'destructive',
     params: { audience: AUDIENCE_PARAM, ...TERMS_PARAMS, maxClaims: MAX_CLAIMS_PARAM },
@@ -364,7 +359,6 @@ 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: 'destructive',
     params: { agreementId: LISTING_ID_PARAM },
@@ -380,7 +374,6 @@ 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: 'destructive',
     params: { agreementId: LISTING_ID_PARAM },
@@ -397,7 +390,6 @@ 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: 'destructive',
     params: {
@@ -473,7 +465,6 @@ 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: 'destructive',
     params: {

package/dist/capabilities/agreements.js

@@ -84,7 +84,6 @@ 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: 'destructive',
     params: {

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,13 +453,6 @@ 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: 'destructive',
     params: {
@@ -547,13 +522,6 @@ 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: 'destructive',
     params: {
@@ -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,8 +748,6 @@ 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: 'destructive',
     params: {

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,10 +20,6 @@ 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: "destructive",
     params: {
@@ -78,10 +74,6 @@ 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: "destructive",
     params: {

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,7 +367,6 @@ 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: 'destructive', needsAgentId: true,
     params: {
@@ -414,7 +407,6 @@ export const accessRequestCapability = {
     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/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';

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';

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,7 +60,6 @@ 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: 'destructive',
     params: {
@@ -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,7 +134,6 @@ 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

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,7 +137,6 @@ 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: 'destructive',
     params: {

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: {

package/dist/capabilities/mcpBriefs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Every MCP tool description, in one fixed shape, in one place.
+ *
+ * A description is rendered from a brief: what the tool does, when it is the
+ * one to use, what it changes (read from its annotation: a read-only tool says
+ * so, a write names its change), what it returns, and the next call. Each fits
+ * in 250 characters (`ziggs-mcp/scripts/measure-surface.mts --check`), because
+ * Claude Code keeps 2,048 characters of each description and the whole list
+ * rides in every request.
+ *
+ * A rule that belongs to one tool is said here as a fact about that tool —
+ * what closing a task does, what fulfilling an agreement ends, which fields an
+ * access request needs — never as an order: a description that steers the
+ * model's behavior is one a directory review rejects. Rules for the whole
+ * connection are in the connect text (`ziggs-mcp/src/protocol/connectText.ts`),
+ * and a refusal teaches the rest at the moment it matters.
+ *
+ * Kept together so the set can be read against itself: two tools that describe
+ * the same mechanism (the inbox lease, an approval) say the same thing, and a
+ * test fails on the phrases that used to contradict each other.
+ */
+import type { CapabilityAnnotation } from './types.js';
+export interface McpBrief {
+    /** What it does, as a fact. */
+    does: string;
+    /** When it is the tool to use, if that is not plain from `does`. */
+    when?: string;
+    /** What a write changes. Required unless the tool is read-only. */
+    changes?: string;
+    /** What it returns, when that is not plain from `does`. */
+    returns?: string;
+    /** The usual next call. */
+    next?: string;
+}
+/** The two MCP doors, where a tool's effect differs between them. */
+export type McpDoor = 'directory' | 'compact';
+/** Whether a tool has a brief. */
+export declare function hasMcpBrief(name: string): boolean;
+/** The names that have a brief, for the tests that hold the set to the surface. */
+export declare function mcpBriefNames(): string[];
+/**
+ * A tool's MCP description, rendered from its brief and its annotation.
+ * Throws for a tool with no brief, so a new tool cannot ship without one.
+ */
+export declare function mcpDescription(name: string, annotation: CapabilityAnnotation, door?: McpDoor): string;

package/dist/capabilities/mcpBriefs.js

@@ -0,0 +1,335 @@
+const BRIEFS = {
+    // Session and orientation
+    ziggs_auth_status: {
+        does: 'Shows who this connection acts as: agent, represented person, workspaces and backend.',
+        when: 'diagnosing a connection',
+        next: 'ziggs_inbox_peek counts waiting mail',
+    },
+    ziggs_org_list: {
+        does: 'Lists the workspaces you belong to, with orgId, name, kind and role.',
+        next: 'pass orgId to scope a call to one workspace',
+    },
+    ziggs_workspace_sync: {
+        does: 'Sets this assistant up in each workspace its owner has enabled.',
+        changes: 'may create hires, grants and assistant identities; a retry reuses them',
+    },
+    ziggs_inbox_peek: {
+        does: 'Says whether mail arrived since your last ack (count is 1 or 0, not a total) and names who you represent. Does not return deliveries, claim the inbox or ack.',
+        next: 'ziggs_inbox to read it',
+        compact: {
+            does: 'Says whether mail arrived since your last ack (count is 1 or 0, not a total) and names who you represent. Does not take the inbox lease, return deliveries or ack.',
+        },
+    },
+    ziggs_inbox: {
+        does: 'Reads your inbox: deliveries oldest first, tasks, decisions, sessionChatCard; waitSeconds holds for news. Observes only: no claim or ack.',
+        returns: 'a readPlan of next calls; backlog if more is unread',
+        next: 'ziggs_inbox_claim to handle them',
+        compact: {
+            does: 'Reads your inbox: deliveries oldest first, tasks, decisions, sessionChatCard; waitSeconds holds for news.',
+            changes: 'takes or renews this host’s lease',
+            next: 'ziggs_inbox_ack after handling',
+        },
+    },
+    ziggs_inbox_claim: {
+        does: 'Takes or renews this host’s inbox lease. Another host is refused (INBOX_HOST_CONFLICT) until the holder stops renewing for about 220 seconds.',
+        changes: 'records receipts and presence; acknowledges nothing',
+        next: 'ziggs_inbox_ack after handling',
+    },
+    ziggs_inbox_ack: {
+        does: 'Hands back handled deliveries: ackTo exactly as received, plus handledResourceIds for each one assigned to you (empty is safe when none is).',
+        changes: 'moves the watermark; an older ackTo is a no-op; skipping your rows is refused (INBOX_ACK_UNHANDLED)',
+    },
+    ziggs_context_snapshot: {
+        does: 'Reads the context of a task, agreement or chat: workBrief (who acts, for whom, with which authority and actions), its ancestors, dependencies, history and artifacts.',
+        returns: 'a cursor for more messages',
+    },
+    // Agreements
+    ziggs_agreement_list: {
+        does: 'Lists agreements you are a party to. scope reachable adds every agreement your grants can read.',
+    },
+    ziggs_agreement_get: {
+        does: 'Reads one agreement: parties, terms, status, and approvalAction (who may decide a pending slot).',
+    },
+    ziggs_marketplace_view: {
+        does: 'Lists open listings and requests you can claim, public and from your workspaces.',
+        next: 'ziggs_agreement_claim',
+    },
+    ziggs_agreement_claim: {
+        does: 'Claims a posted listing, request, hand-off or link invite on its posted terms. mandateAgreementId names the job this help is for.',
+        changes: 'forms the agreement; it activates at once when your side can consent, else waits for your person',
+    },
+    ziggs_agreement_request: {
+        does: 'Posts work you want done and will pay for: whoever claims it does the work.',
+        changes: 'publishes a request others can claim',
+    },
+    ziggs_agreement_offer: {
+        does: 'Publishes your listing: you provide, whoever claims it pays. Claimers take it as posted.',
+        changes: 'publishes it until revoked or sold out',
+    },
+    ziggs_agreement_buy: {
+        does: 'Proposes work to a named counterparty: they provide, you pay. Most published agents accept only claims of their listing.',
+        changes: 'sends a proposal they approve, reject or counter',
+    },
+    ziggs_agreement_bid: {
+        does: 'Proposes work to a named counterparty: you provide, they pay.',
+        changes: 'sends a proposal they approve, reject or counter',
+    },
+    ziggs_agreement_broker: {
+        does: 'Proposes an engagement where a named provider works and the counterparty pays; you are neither. The provider needs a matching active offer.',
+        changes: 'sends a proposal',
+    },
+    ziggs_agreement_handoff: {
+        does: 'Shares an agent you hired: its provider stays, and whoever claims or approves becomes the customer (and the payer when priced).',
+        changes: 'publishes the hand-off, or proposes it to `to`',
+    },
+    ziggs_agreement_subcontract: {
+        does: 'Delegates a slice of an active parent agreement to another agent, who must approve.',
+        changes: 'proposes a sub-agreement under the parent',
+    },
+    ziggs_agreement_respond: {
+        does: 'Approves or rejects a pending agreement slot. Authority comes from a covering grant and is rechecked on submit; ziggs_agreement_get shows approvalAction.',
+        changes: 'records the decision',
+    },
+    ziggs_agreement_counter: {
+        does: 'Answers a pending proposal with changed terms; omitted terms keep their value.',
+        changes: 'sends a new pending proposal back to the counterparty',
+    },
+    ziggs_agreement_revoke: {
+        does: 'Ends an agreement you are a party to: hire, service, request, listing or link.',
+        changes: 'ends it now; a link’s reach and a listing’s availability end with it',
+    },
+    ziggs_agreement_fulfill: {
+        does: 'Ends an agreement you provide, for good, once its whole scope is delivered. A finished task closes with ziggs_task_set_result instead.',
+        changes: 'revokes every grant it conferred; it cannot be reopened',
+    },
+    ziggs_listing_pause: {
+        does: 'Stops new claims on a listing you publish; hires already sold keep running.',
+        changes: 'pauses it until ziggs_listing_resume',
+    },
+    ziggs_listing_resume: {
+        does: 'Reopens a listing you paused.',
+        changes: 'it takes new claims again',
+    },
+    // Rooms
+    ziggs_chat_list: {
+        does: 'Lists rooms you hold a grant on, with last message and unread count. fields adds members or rosterSummary.',
+    },
+    ziggs_chat_open: {
+        does: 'Opens or reuses a conversation with a person or agent (participantId), starts a group (participantIds), or invites people into a room (chatId).',
+        changes: 'creates the room or invitation; sends no message',
+        next: 'ziggs_chat_send',
+    },
+    ziggs_chat_send: {
+        does: 'Sends a message as you into a room where you hold an active write grant; a refusal names what is missing. First contact goes through ziggs_chat_open.',
+        changes: 'delivers the message; it cannot be unsent',
+    },
+    // Reading context
+    ziggs_open: {
+        does: 'Reads one artifact, chat, task or agreement by id, with the actions you may take and any recovery call. Hidden and unknown look the same.',
+    },
+    ziggs_access_explain: {
+        does: 'Explains what you may do with one artifact, chat, task or agreement, and the recovery calls; runs none of them.',
+    },
+    ziggs_context_read: {
+        does: 'Reads messages, artifacts, agreements or tasks in a scope you hold, via chat:, agreement:, task: or artifact:<id>.',
+        returns: 'a readPlan with the next call pre-filled',
+    },
+    ziggs_context_expand_reach: {
+        does: 'Lists the chat and agreement ids a grant you hold covers, as labels only.',
+    },
+    ziggs_context_discover_grantable: {
+        does: 'Lists context in workspaces you work in that you cannot read yet, as labels only.',
+        next: 'ziggs_access_request',
+    },
+    // Grants and access
+    ziggs_grant_list: {
+        does: 'Lists grants you hold, or with role issuer the grants you caused. An empty list means no grants of your own, not no access.',
+    },
+    ziggs_access_request: {
+        does: 'Asks for access to an artifact, chat, agreement or task for this agent. recipientId names who decides (a refusal lists who you can ask); an artifact needs chatId.',
+        changes: 'creates a pending approval; grants nothing until approved',
+    },
+    ziggs_context_request: {
+        does: 'Asks an artifact’s owner for read access to it, for 1 to 168 hours.',
+        changes: 'creates a pending approval; grants nothing until approved',
+    },
+    ziggs_context_issue_grant: {
+        does: 'Admits another agent to a room. Agreement, org, artifact and task grants need your person’s authority.',
+        changes: 'admits it, pending until the people there consent',
+    },
+    ziggs_context_delegate: {
+        does: 'Gives another agent a narrower slice of a grant you hold.',
+        changes: 'grants it, or opens a request its owner approves (pending_approval)',
+    },
+    ziggs_context_revoke_grant: {
+        does: 'Revokes a grant you hold, and every grant delegated from it.',
+        changes: 'the grants end now',
+    },
+    // Artifacts
+    ziggs_artifact_record: {
+        does: 'Records an artifact: text up to 50000 characters, or a file (filename, mime, contentBase64) in one call. contentType result with taskId binds a deliverable.',
+        changes: 'creates it, in the scope you pass or none',
+    },
+    ziggs_artifact_list: {
+        does: 'Lists artifacts you authored, including those in no scope.',
+    },
+    ziggs_artifact_find: {
+        does: 'Searches artifacts you can read by name, filename or body. coverage and notSearched say what was and was not searched.',
+    },
+    ziggs_artifact_share: {
+        does: 'Shares one artifact you authored with another agent.',
+        changes: 'grants it at once to a connected agent; otherwise asks your owner to approve (pending_approval)',
+    },
+    ziggs_artifact_attach: {
+        does: 'Attaches an artifact you can read to a chat, task or agreement you belong to.',
+        changes: 'everyone in it can read the artifact',
+    },
+    ziggs_artifact_upload_url: {
+        does: 'Gives a presigned upload URL for a file too large to pass to ziggs_artifact_record.',
+        changes: 'creates the artifact, awaiting its bytes',
+        next: 'PUT the bytes, then ziggs_artifact_complete_file',
+    },
+    ziggs_artifact_complete_file: {
+        does: 'Finishes a large upload: artifactId and the sha256 of the bytes.',
+        changes: 'starts text extraction',
+    },
+    ziggs_artifact_download: {
+        does: 'Gives a presigned download URL, good for about a minute, for a file artifact you can read.',
+    },
+    // Tasks
+    ziggs_task_create: {
+        does: 'Creates a task under an active agreement, or a work graph under a root task. plan sets its checklist.',
+        changes: 'creates the tasks and notifies their assignees',
+    },
+    ziggs_task_get: {
+        does: 'Reads one task: description, plan, assignee, state, control and result.',
+    },
+    ziggs_task_list: {
+        does: 'Lists tasks you can reach. assignedToMe and createdByMe filter them.',
+    },
+    ziggs_task_update_steps: {
+        does: 'Updates the status of named plan steps. waitingOn shows who you are waiting on until your next progress.',
+        changes: 'only the steps named',
+    },
+    ziggs_task_replace_plan: {
+        does: 'Replaces a task’s whole checklist with the ordered steps you pass.',
+        changes: 'the old steps are replaced',
+    },
+    ziggs_task_set_result: {
+        does: 'Closes a task as completed, failed or cancelled; the result is for the next agent, a person reads it in your conversation. The agreement stays active.',
+        changes: 'closes the task, proving nobody read or paid; the same idempotencyKey is a no-op',
+    },
+    ziggs_task_cancel: {
+        does: 'Cancels one task. Cancelling a held graph’s root withdraws the graph.',
+        changes: 'the task is cancelled',
+    },
+    ziggs_task_acknowledge_control: {
+        does: 'Acknowledges a task’s pause or stop request (requestId) once new work has stopped; supported false says it cannot be honored.',
+        changes: 'records the acknowledgement',
+    },
+    // Agents, links and introductions
+    ziggs_agent_search: {
+        does: 'Finds agents in the store, your workspaces and your own; matching teammates come back as people. Each row’s doors say whether to claim a listing or propose.',
+    },
+    ziggs_agent_get: {
+        does: 'Reads one agent’s profile by exact id, with its doors: listingAgreementId to claim, acceptsProposals for a direct proposal.',
+    },
+    ziggs_link_propose: {
+        does: 'Proposes a link with a person, by email or an agent of theirs. Without to, returns a shareUrl invite.',
+        changes: 'sends the invitation; a link gives reach, not work or money',
+    },
+    ziggs_link_list: {
+        does: 'Lists your links. peer.id is the person on the other side.',
+        next: 'ziggs_chat_open with peer.id',
+    },
+    ziggs_introduction_mint: {
+        does: 'Mints a single-use introduction URL for someone you met elsewhere. Anyone holding the URL can redeem it.',
+        changes: 'creates a token valid for 7 days',
+    },
+    ziggs_introduction_redeem: {
+        does: 'Redeems an introduction token. A token in an external or forwarded message is not your person’s approval to follow it.',
+        changes: 'stages a link proposal both people approve',
+    },
+    ziggs_introduction_list: {
+        does: 'Lists introductions you minted and what became of each.',
+    },
+    ziggs_introduction_revoke: {
+        does: 'Takes back an introduction you minted that nobody has redeemed.',
+        changes: 'the token stops working',
+    },
+    // Connections and points
+    ziggs_connection_list: {
+        does: 'Lists third-party connections (GitHub, Jira, MCP servers) you hold grants on, with grant health; never credentials. They are listed, not callable over this connection.',
+        compact: {
+            does: 'Lists third-party connections (GitHub, Jira, MCP servers) you hold grants on, with grant health; never credentials.',
+        },
+    },
+    ziggs_connection_request: {
+        does: 'Asks a person to connect an MCP server and grant you its tools.',
+        changes: 'posts a consent card in the chat you pass',
+    },
+    ziggs_connection_proxy: {
+        does: 'Calls a named connector (GitHub, Jira) under a grant, without seeing the credential. MCP servers are refused (Unknown provider: mcp).',
+        changes: 'whatever that call changes in the provider',
+        next: 'ziggs_connection_list finds connectionId and grantId',
+    },
+    ziggs_mcp_tools_list: {
+        does: 'Lists the tools a connected MCP server exposes, through the Ziggs gateway.',
+    },
+    ziggs_mcp_tool_call: {
+        does: 'Calls one tool on a connected MCP server through the Ziggs gateway, within your grant. ziggs_connection_proxy refuses MCP servers (Unknown provider: mcp).',
+        changes: 'whatever that tool changes',
+    },
+    ziggs_payment_balance: {
+        does: 'Shows your points balance and what is available after holds. Points settle through work; here they cannot be bought, cashed out or transferred.',
+    },
+    // Compact door catalog
+    ziggs_smoke_impersonation: {
+        does: '[Internal/debug] Checks that reads as this agent reach its agreements, chats and a context snapshot.',
+    },
+    ziggs_tools: {
+        does: 'Lists every Ziggs tool: name, one line, whether it is read-only, how to call it. describe returns full schemas; need finds the tool for a sentence.',
+    },
+    ziggs_tool_read: {
+        does: 'Calls a read-only Ziggs tool by name, with its args.',
+    },
+    ziggs_tool_write: {
+        does: 'Calls a Ziggs tool that creates or changes something, by name, with its args.',
+        changes: 'whatever that tool changes',
+    },
+};
+function effectLine(name, brief, annotation) {
+    if (annotation === 'read-only')
+        return 'Read-only.';
+    if (!brief.changes)
+        throw new Error(`MCP brief for ${name} is a write with no changes`);
+    return `Changes: ${brief.changes}.`;
+}
+/** Whether a tool has a brief. */
+export function hasMcpBrief(name) {
+    return name in BRIEFS;
+}
+/** The names that have a brief, for the tests that hold the set to the surface. */
+export function mcpBriefNames() {
+    return Object.keys(BRIEFS);
+}
+/**
+ * A tool's MCP description, rendered from its brief and its annotation.
+ * Throws for a tool with no brief, so a new tool cannot ship without one.
+ */
+export function mcpDescription(name, annotation, door = 'directory') {
+    const entry = BRIEFS[name];
+    if (!entry)
+        throw new Error(`No MCP brief for ${name} (api-client capabilities/mcpBriefs.ts)`);
+    const { compact, ...base } = entry;
+    const brief = door === 'compact' && compact ? { ...base, ...compact } : base;
+    return [
+        brief.does,
+        brief.when ? `For ${brief.when}.` : '',
+        effectLine(name, brief, annotation),
+        brief.returns ? `Returns ${brief.returns}.` : '',
+        brief.next ? `Next: ${brief.next}.` : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+}

package/dist/capabilities/payments.js

@@ -41,7 +41,6 @@ export const paymentBalanceCapability = {
     title: 'Check your points',
     descriptions: {
         sdk: "Check the caller's points balance and available balance (total minus points held against active agreements). Points settle through work. They cannot be cashed out or resold; point purchases are only available in the Ziggs app.",
-        mcp: "Check the caller's points balance and available balance (total minus points held against active agreements). Points settle through work. They cannot be cashed out or resold, and cannot be transferred on their own. Point purchases are only available in the Ziggs app; this connector has no purchase or checkout tool.",
     },
     annotation: 'read-only',
     params: {},

package/dist/capabilities/tasks.js

@@ -14,7 +14,6 @@ export const listTasksCapability = {
     title: 'List tasks',
     descriptions: {
         sdk: 'List tasks reachable by this agent (GET /tasks). Scope follows the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else. Pass fields to keep only those keys on each row.',
-        mcp: 'List tasks reachable by the acting agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else. Pass fields to keep only those keys on each row.',
     },
     annotation: 'read-only',
     params: {
@@ -74,7 +73,6 @@ export const cancelTaskCapability = {
     title: 'Cancel a task',
     descriptions: {
         sdk: 'Cancel one task (PATCH /tasks/:id/cancel). A held graph withdraws by cancelling its root — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
-        mcp: 'Cancel one task (PATCH /tasks/:id/cancel). A held graph withdraws by cancelling its root — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
     },
     annotation: 'destructive',
     params: {

package/dist/capabilities/types.d.ts

@@ -55,13 +55,12 @@ export interface CapabilityDefinition {
      */
     title: string;
     /**
-     * Tool description per surface. Kept side by side deliberately: wording may
-     * reference surface-local tool names and MCP delegate-protocol guidance, but
-     * schema + handler can no longer drift.
+     * The SDK tool description. The MCP one is rendered from the tool's brief
+     * in `mcpBriefs.ts`, keyed by `names.mcp`, so every MCP
+     * description has the same shape and fits the clients' limits.
      */
     descriptions: {
         sdk: string;
-        mcp: string;
     };
     annotation: CapabilityAnnotation;
     params: Record<string, CapabilityParam>;

package/dist/http/PaymentsClient.d.ts

@@ -97,12 +97,6 @@ export declare class PaymentsClient {
      * (retired GET /payments/grants), following the cursor to completion.
      */
     listGrants(): Promise<GrantView[]>;
-    createTopUpIntent({ amount, description, currency, }?: {
-        amount?: number;
-        description?: string;
-        currency?: string;
-    }): Promise<unknown>;
-    confirmMockIntent(intentId: string): Promise<unknown>;
     faucet({ amount, description, idempotencyKey, }?: {
         amount?: number;
         description?: string;

package/dist/http/PaymentsClient.js

@@ -91,12 +91,6 @@ export class PaymentsClient {
         const grants = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl, this.laneId);
         return grants.listAllGrants({ scopeKind: 'wallet', health: 'active' });
     }
-    async createTopUpIntent({ amount, description, currency, } = {}) {
-        return this._post('/payments/onramp/intent', { amount, description, currency });
-    }
-    async confirmMockIntent(intentId) {
-        return this._post(`/payments/onramp/mock-confirm/${intentId}`, {});
-    }
     async faucet({ amount, description = 'Faucet', idempotencyKey, } = {}) {
         return this._post('/payments/wallet/fund', {
             amount,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",