@brightbeamai/chap-coordinator-mcp 0.2.13 → 0.3.1

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(src_exports, {
   SCHEMAS: () => SCHEMAS,
   SUPPORTED_PROTOCOL_VERSIONS: () => SUPPORTED_PROTOCOL_VERSIONS,
   ServerDiscoverRequestSchema: () => ServerDiscoverRequestSchema,
+  TOOL_ANNOTATIONS: () => TOOL_ANNOTATIONS,
   TOOL_DESCRIPTIONS: () => TOOL_DESCRIPTIONS,
   TOOL_NAMES: () => TOOL_NAMES,
   UNSUPPORTED_PROTOCOL_VERSION: () => UNSUPPORTED_PROTOCOL_VERSION,
@@ -184,8 +185,8 @@ var SCHEMAS = {
       task_id: TASK_ID,
       state: {
         type: "string",
-        enum: ["in_progress", "review_requested", "declined", "paused", "cancelled", "completed"],
-        description: "The state to move the task to. Only the transitions in SPECIFICATION.md 8.1 are legal from the task's current state; others are refused with -32602. A task marked review_required cannot be moved to 'completed' here: submit the output with chap.task.complete, which opens the review."
+        enum: ["in_progress", "declined", "cancelled", "completed"],
+        description: "The state to move the task to. Only the transitions in SPECIFICATION.md 8.1 are legal from the task's current state; others are refused with -32602. A review opens with chap.review.request, or with chap.task.complete on a task that requires one, so 'review_requested' is not a target here. A task marked review_required cannot be moved to 'completed' here: submit the output with chap.task.complete, which opens the review."
       },
       progress_note: { type: "string", description: "Short note on what changed, kept in the task's history." }
     },
@@ -221,7 +222,12 @@ var SCHEMAS = {
         properties: {
           method: { type: "string", description: "Return only entries for this CHAP method, e.g. 'decide.override'. Matched in full, without the 'chap.' tool-name prefix." },
           from: { type: "string", description: "Return only entries whose actor is this participant URI." },
-          task_id: { type: "string", description: "Return only entries about this task." }
+          task_id: { type: "string", description: "Return only entries about this task." },
+          outcome: {
+            type: "string",
+            enum: ["accepted", "refused"],
+            description: "Return only accepted calls, or only the refused attempts the coordinator recorded. Omit for both."
+          }
         }
       }
     },
@@ -341,8 +347,9 @@ var SCHEMAS = {
         description: "The successor task to open for the escalation target.",
         properties: {
           kind: { type: "string", description: "Task kind for the successor. Defaults to the original's kind." },
-          assignee: { ...PARTICIPANT_URI, description: "Who the escalation goes to. Must be a workspace member." },
-          input: { type: "object", additionalProperties: true, description: "Input payload for the successor. It defaults to an empty object rather than the original's input, so anything the new assignee needs has to be restated here." }
+          assignee: { ...PARTICIPANT_URI, description: "Who the escalation goes to. Must be a workspace member who is not paused: a paused assignee is refused with -32063." },
+          input: { type: "object", additionalProperties: true, description: "Input payload for the successor. It defaults to an empty object rather than the original's input, so anything the new assignee needs has to be restated here." },
+          mode: { type: "string", enum: ["shadow", "trial", "production"], description: "Mode for the successor, defaulting to the original's. A mode above the workspace's current ceiling is refused with -32040, so after the ceiling is lowered a task is escalated by naming a mode within it." }
         },
         required: ["assignee"]
       }
@@ -533,7 +540,7 @@ var SCHEMAS = {
         type: "string",
         enum: ["task", "participant", "workspace"],
         default: "task",
-        description: "What the resume applies to. 'task' returns a paused task to 'in_progress'; a task that is not paused is refused with -32061. 'participant' allows that member to be assigned tasks again. 'workspace' returns the workspace to active."
+        description: "What the resume applies to. 'task' returns a paused task to the state it held at the pause; a task that is not paused is refused with -32061. 'participant' allows that member to be assigned tasks again. 'workspace' returns the workspace to active."
       },
       task_id: TASK_ID,
       participant_uri: { ...PARTICIPANT_URI, description: "Whose work to resume, when scope is 'participant'. Must be a workspace member." }
@@ -582,8 +589,10 @@ var SCHEMAS = {
         description: "The replacement task.",
         properties: {
           kind: { type: "string", description: "Task kind for the successor. Required." },
-          assignee: { ...PARTICIPANT_URI, description: "Who takes the replacement on. Defaults to the superseded task's assignee, and must be a workspace member." },
-          input: { type: "object", additionalProperties: true, description: "Input payload for the successor. Defaults to an empty object." }
+          assignee: { ...PARTICIPANT_URI, description: "Who takes the replacement on. Defaults to the superseded task's assignee, and must be a workspace member who is not paused." },
+          input: { type: "object", additionalProperties: true, description: "Input payload for the successor. Defaults to an empty object." },
+          mode: { type: "string", enum: ["shadow", "trial", "production"], description: "Mode for the successor, defaulting to the superseded task's. A mode above the workspace's current ceiling is refused with -32040." },
+          review_required: { type: "boolean", description: "Whether completing the successor needs a reviewer decision. A successor of a task that requires review requires it whatever is passed here, and under modes/1.0 so does a trial-mode successor." }
         },
         required: ["kind"]
       },
@@ -614,7 +623,7 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      candidates: { type: "array", items: PARTICIPANT_URI, description: "Candidate assignees. An empty list is refused with -32513. Candidates that are not workspace members are dropped, and if none remain the call is refused with -32510. The default policy selects the first remaining candidate; an operator-supplied routing policy may select on any basis." }
+      candidates: { type: "array", items: PARTICIPANT_URI, description: "Candidate assignees. An empty list is refused with -32513. The default policy takes the first candidate that is a workspace member and is not paused, and refuses the call with -32510 when there is none. An operator-supplied routing policy may select on any basis; a choice that is not a member is refused with -32510, and one who is paused with -32063." }
     },
     required: ["workspace", "from", "task_id", "candidates"]
   },
@@ -751,52 +760,147 @@ var TOOL_DESCRIPTIONS = {
   // Core
   "chap.workspace.create": "Create a workspace: the container for the participants, tasks and audit log of one piece of collaborative work. Returns the workspace id, which every later call carries.",
   "chap.workspace.describe": "Report the current state of a workspace: its members, enabled profiles, audit length, and task and override counts.",
-  "chap.workspace.set_profiles": "Replace the set of profiles enabled on a workspace. Enabling audit-scitt/1.0 on a workspace that already has entries leaves those entries outside the hash chain.",
+  "chap.workspace.set_profiles": "Replace the whole set of profiles enabled on a workspace. The list is not merged: any profile absent from it is dropped, so send the complete set you want. Enabling audit-scitt/1.0 on a workspace that already has entries starts the chain from that point and leaves the earlier entries permanently outside it, which chap.audit.verify_chain then reports as not_evaluated. Prefer setting profiles at chap.workspace.create, where no entries exist yet to strand.",
   "chap.participant.join": "Add a participant to a workspace. The type given, human, agent, service, group or workspace, decides whether they are eligible to review work that requires it.",
-  "chap.participant.leave": "Remove a participant from a workspace. Entries they have already written stay in the audit log.",
-  "chap.task.create": "Create a task: a unit of work assigned to one participant. Set review_required to make the task's completion depend on a reviewer decision rather than on the assignee.",
+  "chap.participant.leave": "Remove a participant from a workspace. Entries they have already written stay in the audit log and their past signatures still verify, so leaving is not a way to withdraw a decision. They can no longer be assigned tasks or act as a reviewer, and returning means a fresh chap.participant.join.",
+  "chap.task.create": "Create a task: a unit of work assigned to one participant. Set review_required to make completion depend on a reviewer decision rather than on the assignee. Returns a task_id that the rest of the lifecycle takes. Supplying idempotency_key is what makes a retry safe: a repeat carrying a key already seen returns the original task, while a repeat without one creates a second task. Assigning to a paused member is refused.",
   "chap.task.update": "Move a task to a new state. Only the transitions in the specification's lifecycle table are accepted, and a task that requires review cannot be completed here.",
   "chap.task.complete": "Submit a task's output. A task that requires review does not complete: the output is held as the artefact under review, the task moves to review_requested, and a reviewer decision completes it. Any other task completes immediately.",
-  "chap.audit.read": "Read entries from a workspace's audit log, optionally within a sequence range and filtered by method, sender or task.",
+  "chap.audit.read": "Read entries from a workspace's audit log, optionally within a sequence range and filtered by method, sender, task or outcome. This is the query surface for everything the workspace has recorded, decisions and overrides included. An accepted call is under 'envelope'. A refused attempt the coordinator recorded, such as a decision by someone the review was not addressed to, is under 'request' with an 'outcome' giving the error code, and it did not take effect. Reads only: it records nothing, so it never appears in its own output. Entries come back as recorded, without aggregation, so grouping them, by tag for instance, is the reader's job.",
   // review/1.0
   "chap.review.request": "Open a review on a task and address it to one or more reviewers. They then call chap.decide.approve, chap.decide.reject, chap.decide.override or chap.abstain.declare. Repeating the request with the same artefact adds reviewers to the open review.",
-  "chap.decide.approve": "Approve the artefact under review. The task completes once the review's rule is satisfied.",
-  "chap.decide.reject": "Reject the artefact under review. The task is declined, or returns to in_progress if request_revision is set.",
+  "chap.decide.approve": "Approve the artefact under review as it stands. Only a reviewer the review was addressed to may decide, and anyone else is refused with -32011. The task completes once the review's rule is satisfied, so under all_approve or quorum:N an approval may leave the review open awaiting others. Use chap.decide.override instead to accept a corrected version.",
+  "chap.decide.reject": "Reject the artefact under review. The task is declined, or returns to in_progress when request_revision is set, which is the choice between ending the work and sending it back. Only a reviewer the review was addressed to may decide. Use chap.decide.override instead to correct the artefact and accept it rather than refuse it.",
   "chap.decide.override": "Correct the artefact under review with an RFC 6902 JSON Patch and accept the result. The patch, the rationale and any tags are recorded together, so the audit log holds what was changed and why, rather than only that the work was not accepted as written.",
-  "chap.abstain.declare": "Stand aside from a review, giving a reason and a category. The task moves to abstained.",
-  "chap.escalate.raise": "Hand a task upwards. The original moves to escalated and is linked to a new task opened for whoever takes it on. The successor starts with an empty input unless one is supplied.",
+  "chap.abstain.declare": "Stand aside from a review this participant cannot decide, for example on a conflict of interest or for want of context. Use it in place of chap.decide.reject, which judges the work; abstaining judges nothing and leaves the artefact intact. It requires an open review addressed to the caller and answers -32010 otherwise. The task moves to abstained, which is not terminal: chap.escalate.raise or a fresh chap.review.request can still carry it forward.",
+  "chap.escalate.raise": "Hand a task upwards, where the current holder can act but should not decide alone. The original moves to escalated and is linked to a new task for whoever takes it on. Use chap.handoff.propose to pass work sideways without that link, and chap.control.supersede to replace a task outright. The successor starts with an empty input unless one is supplied, so restate whatever the new assignee needs. A completed, cancelled or superseded task cannot be escalated. The successor takes the mode new_task.mode names, or else the original's, and requires review when the original did, or when it is a trial task under modes/1.0. A paused assignee is refused with -32063, and a mode above the workspace's current ceiling with -32040; after the ceiling is lowered, name a mode within it.",
   // whisper/1.0
   "chap.whisper.ask": "Put one question to one or more participants, with a deadline and a default. If the deadline passes unanswered the default applies, so a task is never blocked waiting on a reply.",
-  "chap.whisper.answer": "Answer an open whisper. Where the question carried options, the answer must name one of them.",
+  "chap.whisper.answer": "Answer an open whisper. Where the question carried options, the answer must name one of their ids and any other value is refused with -32022. A whisper already answered is refused with -32020 and one past its deadline with -32021, in which case the default supplied at chap.whisper.ask has already been applied.",
   // deliberation/1.0
-  "chap.deliberate.open": "Open a deliberation among several participants under a stated voting rule: any_one_approves, all_approve, quorum:N, weighted_vote:T or weighted_vote_with_veto:T.",
-  "chap.deliberate.comment": "Record a comment on an open deliberation, so the reasoning is on the audit log alongside the votes.",
-  "chap.deliberate.vote": "Cast a yea, nay or abstain in an open deliberation. Each participant votes once.",
-  "chap.deliberate.close": "Close a deliberation and compute its outcome from the votes cast under its rule.",
+  "chap.deliberate.open": "Open a group decision among several participants under a stated voting rule: any_one_approves, all_approve, quorum:N, weighted_vote:T or weighted_vote_with_veto:T. Use it where several people must weigh in on one question; chap.review.request is the tool for judging one participant's output. Returns a deliberation_id that the comment, vote and close tools all take. The participant list, rule, weights and veto map are fixed at open, so the terms are settled before anyone votes. No outcome exists until chap.deliberate.close computes one.",
+  "chap.deliberate.comment": "Record a comment on an open deliberation, so the reasoning behind a vote survives alongside the tally. Comments carry no weight in the outcome and may be added by any participant at any point before chap.deliberate.close.",
+  "chap.deliberate.vote": "Cast a yea, nay or abstain in an open deliberation. Each participant votes once and a second attempt answers -32031, so a vote cannot be revised. An abstention is recorded but counts as neither side, which under all_approve or quorum:N withholds the approval those rules need. The tally is computed later, by chap.deliberate.close.",
+  "chap.deliberate.close": "Close a deliberation and compute its outcome from the votes cast under its rule. Closing is final: further comments and votes are refused with -32032. Calling it again on a closed deliberation returns the same outcome and changes nothing, so a retry is safe. Votes never cast are simply absent from the tally rather than counted as abstentions.",
   // handoff/1.0
   "chap.handoff.propose": "Propose handing one or more tasks to another participant or a group, with the context needed to pick them up. Every task must currently be assigned to the proposer.",
-  "chap.handoff.accept": "Accept a proposed handoff. The accepted tasks are reassigned to the accepting participant.",
-  "chap.handoff.decline": "Decline a proposed handoff, with a reason and optionally a suggestion of who should take it instead.",
+  "chap.handoff.accept": "Accept a proposed handoff. The accepted tasks are reassigned to the accepting participant, which is the point at which responsibility actually moves. Omitting accepted_task_ids accepts all of them. Accepting resolves the proposal for good: a later accept or decline on the same handoff answers -32051. A paused participant cannot accept and is refused with -32063.",
+  "chap.handoff.decline": "Decline a proposed handoff. The tasks stay with the proposer and nothing is reassigned, which is the difference from chap.handoff.accept. Declining resolves the proposal for good: a later accept or decline on the same handoff answers -32051, and trying again means a fresh proposal. The reason is recorded so the proposer can route the work elsewhere.",
   // control/1.0
   "chap.control.pause": "Pause work. Scoped to a task it moves that task to paused; to a participant it stops new tasks being assigned to them; to the workspace it refuses every method except describing, reading the audit log, joining, leaving and resuming.",
-  "chap.control.resume": "Resume work paused at the same scope: a task returns to in_progress, a participant can be assigned tasks again, a workspace returns to active.",
+  "chap.control.resume": "Resume work paused at the same scope: a task returns to the state it held at the pause, a participant can be assigned tasks again, a workspace returns to active.",
   "chap.control.cancel": "Cancel a task. Cancelled is terminal, and a task that has already settled cannot be cancelled.",
-  "chap.control.snapshot": "Capture the workspace state as an artefact and return its id, which chap.control.rollback takes as its target.",
+  "chap.control.snapshot": "Capture the workspace state as an artefact before a change you may want to undo. Returns a snapshot artefact id, which is the only thing chap.control.rollback accepts as a target; the label is for a human reading the log and cannot be used to select it. Taking a snapshot changes nothing. Note that a rollback restores only the mode ceiling and member roles, so a snapshot is a narrow safety net rather than a general undo.",
   "chap.control.rollback": "Restore workspace state from a snapshot. The mode ceiling and member roles are restored; the rollback is appended to the audit log rather than rewriting it.",
-  "chap.control.supersede": "Replace a task with a successor in one call. The original moves to superseded and stays linked to its replacement.",
+  "chap.control.supersede": "Replace a task with a successor in one call. The original moves to superseded and stays linked to its replacement. The successor requires review when the original did, whatever its own review_required says, and a paused assignee is refused with -32063.",
   "chap.control.set_mode_ceiling": "Set the highest operating mode tasks in this workspace may request. A task above the ceiling is refused.",
   // routing/1.0
-  "chap.task.route": "Choose an assignee for a task from a list of candidates and record a route_decision artefact naming the policy, the candidate chosen, and the alternatives it passed over.",
+  "chap.task.route": "Choose an assignee for a task from a list of candidates and reassign the task to the one selected. Use it where the choice itself belongs on the record: it writes a route_decision artefact naming the policy, the candidate chosen and the alternatives passed over, none of which is captured by setting assignee directly on chap.task.create. The default policy takes the first candidate that is a workspace member and is not paused. An operator-supplied policy may choose on any basis, and the call is refused with -32510 when its choice is not a member, or with -32063 when its choice is paused.",
   "chap.review.depth": "Decide how much review a task warrants, skip, spot_check or full, from its routing hints. Records a route_decision artefact giving the rule that produced the answer.",
-  "chap.escalate.auto": "Evaluate a task's routing hints against the escalation policy and report whether it should be escalated, and to whom. Records a route_decision artefact.",
+  "chap.escalate.auto": "Evaluate a task's routing hints against the escalation policy and report whether it should be escalated, and to whom. It decides only: a route_decision artefact is recorded but the task does not move, so act on the answer with chap.escalate.raise. The default policy escalates on criticality critical, or high with confidence below 0.6.",
   // security-signed/1.0
   "chap.participant.rotate_key": "Retire a participant's signing key and register its replacement. The old key stays in the key history with a valid_until timestamp, so envelopes it signed still verify.",
   "chap.participant.revoke_key": "Revoke a signing key, for example after a device is lost. Signatures presented with it are refused from then on. Revoking another participant's key requires the admin role.",
   // audit-scitt/1.0
   "chap.audit.submit_to_scitt": "Build COSE_Sign1-shaped statements for a range of audit entries and submit them to the configured SCITT transparency service. Where none is configured the statements are returned for submission out of band.",
-  "chap.audit.verify_receipt": "Verify a SCITT receipt through the configured verifier. Verification fails closed where no verifier is configured.",
+  "chap.audit.verify_receipt": "Check a receipt returned by an external SCITT transparency service, confirming that service logged the statement. This is the external half of verification; chap.audit.verify_chain checks the local prev-hash chain instead, and the two answer different questions. Verification is delegated to a hook the deployment supplies and fails closed with -32082 when none is configured, so a missing verifier can never read as a pass. Reads only: nothing is recorded.",
   "chap.audit.verify_chain": "Replay a workspace's prev-hash chain. Only status verified with ok true means the log was checked and is intact. Status not_evaluated with ok false means part of the log was never checked, so its integrity is unknown and must not be reported as verified; entries_unchecked says how much. An error means the chain is broken or absent."
 };
+var READ_ONLY = /* @__PURE__ */ new Set([
+  "chap.workspace.describe",
+  "chap.audit.read",
+  "chap.audit.verify_chain",
+  "chap.audit.verify_receipt",
+  // Submitting reads the chain and sends it onward. It changes nothing here,
+  // which is what readOnlyHint claims; openWorldHint carries the fact that it
+  // reaches a service outside this coordinator.
+  "chap.audit.submit_to_scitt"
+]);
+var DESTRUCTIVE = /* @__PURE__ */ new Set([
+  "chap.workspace.set_profiles",
+  // replaces the profile set; can strand entries outside the chain
+  "chap.participant.leave",
+  // removes a member
+  "chap.participant.revoke_key",
+  // invalidates a key from then on
+  "chap.control.cancel",
+  // cancelled is terminal
+  "chap.control.supersede",
+  // superseded is terminal
+  "chap.control.rollback"
+  // overwrites the mode ceiling and member roles
+]);
+var IDEMPOTENT = /* @__PURE__ */ new Set([
+  "chap.workspace.describe",
+  "chap.audit.read",
+  "chap.audit.verify_chain",
+  "chap.audit.verify_receipt",
+  "chap.participant.join",
+  // a re-join is additive and adds no duplicate member
+  "chap.participant.leave",
+  // leaving twice leaves the same absence
+  "chap.control.pause",
+  // pausing an already paused target changes nothing
+  "chap.control.set_mode_ceiling",
+  // setting the ceiling it already has changes nothing
+  "chap.deliberate.close"
+  // returns the same outcome, recomputing nothing
+]);
+var OPEN_WORLD = /* @__PURE__ */ new Set([
+  "chap.audit.submit_to_scitt",
+  "chap.audit.verify_receipt"
+]);
+var TITLES = {
+  "chap.workspace.create": "Create workspace",
+  "chap.workspace.describe": "Describe workspace",
+  "chap.workspace.set_profiles": "Replace workspace profiles",
+  "chap.participant.join": "Add participant",
+  "chap.participant.leave": "Remove participant",
+  "chap.task.create": "Create task",
+  "chap.task.update": "Change task state",
+  "chap.task.complete": "Submit task output",
+  "chap.audit.read": "Read audit log",
+  "chap.review.request": "Request review",
+  "chap.decide.approve": "Approve",
+  "chap.decide.reject": "Reject",
+  "chap.decide.override": "Override with a correction",
+  "chap.abstain.declare": "Abstain from review",
+  "chap.escalate.raise": "Escalate task",
+  "chap.whisper.ask": "Ask a whisper",
+  "chap.whisper.answer": "Answer a whisper",
+  "chap.deliberate.open": "Open deliberation",
+  "chap.deliberate.comment": "Comment on deliberation",
+  "chap.deliberate.vote": "Vote in deliberation",
+  "chap.deliberate.close": "Close deliberation",
+  "chap.handoff.propose": "Propose handoff",
+  "chap.handoff.accept": "Accept handoff",
+  "chap.handoff.decline": "Decline handoff",
+  "chap.control.pause": "Pause work",
+  "chap.control.resume": "Resume work",
+  "chap.control.cancel": "Cancel task",
+  "chap.control.snapshot": "Snapshot workspace",
+  "chap.control.rollback": "Roll back to snapshot",
+  "chap.control.supersede": "Supersede task",
+  "chap.control.set_mode_ceiling": "Set mode ceiling",
+  "chap.task.route": "Route task to an assignee",
+  "chap.review.depth": "Decide review depth",
+  "chap.escalate.auto": "Evaluate auto-escalation",
+  "chap.participant.rotate_key": "Rotate signing key",
+  "chap.participant.revoke_key": "Revoke signing key",
+  "chap.audit.submit_to_scitt": "Anchor audit log in SCITT",
+  "chap.audit.verify_receipt": "Verify SCITT receipt",
+  "chap.audit.verify_chain": "Verify audit chain"
+};
+var TOOL_ANNOTATIONS = Object.fromEntries(
+  Object.keys(TOOL_DESCRIPTIONS).map((name) => [name, {
+    title: TITLES[name] ?? name,
+    readOnlyHint: READ_ONLY.has(name),
+    // Meaningful only when readOnlyHint is false, per the specification.
+    destructiveHint: DESTRUCTIVE.has(name),
+    idempotentHint: IDEMPOTENT.has(name),
+    openWorldHint: OPEN_WORLD.has(name)
+  }])
+);
 
 // src/envelope.ts
 var import_types = require("@modelcontextprotocol/sdk/types.js");
@@ -859,7 +963,7 @@ var ServerDiscoverRequestSchema = import_zod.z.object({
 function makeChapMcpServer(coord, options = {}) {
   const serverInfo = {
     name: options.name ?? "chap",
-    version: options.version ?? "0.2.13"
+    version: options.version ?? "0.3.1"
   };
   const server = new import_server.Server(
     serverInfo,
@@ -872,12 +976,20 @@ function makeChapMcpServer(coord, options = {}) {
   let counter = 0;
   const nextId = options.envelopeIdFactory ?? (() => `mcp-${++counter}`);
   const filter = options.toolFilter ?? (() => true);
-  const enabledTools = TOOL_NAMES.filter((name) => filter(name) && methodForTool(name) !== null).map((name) => ({
-    name,
-    title: name,
-    description: TOOL_DESCRIPTIONS[name] ?? `CHAP method ${methodForTool(name)}.`,
-    inputSchema: SCHEMAS[name]
-  }));
+  const enabledTools = TOOL_NAMES.filter((name) => filter(name) && methodForTool(name) !== null).map((name) => {
+    const ann = TOOL_ANNOTATIONS[name];
+    return {
+      name,
+      // The title was the tool name, which told a reader nothing they could
+      // not already see. The annotation carries a readable one.
+      title: ann?.title ?? name,
+      description: TOOL_DESCRIPTIONS[name] ?? `CHAP method ${methodForTool(name)}.`,
+      inputSchema: SCHEMAS[name],
+      // Behavioural hints. Without these a client has only the prose to go
+      // on when deciding whether a call is safe to make or to retry.
+      ...ann ? { annotations: ann } : {}
+    };
+  });
   server.setRequestHandler(import_types2.ListToolsRequestSchema, async (request) => {
     const era = classifyEnvelope(request.params);
     if (era === "legacy") return { tools: enabledTools };
@@ -897,7 +1009,7 @@ function makeChapMcpServer(coord, options = {}) {
       resultType: "complete",
       supportedVersions: SUPPORTED_PROTOCOL_VERSIONS,
       capabilities: { tools: {} },
-      instructions: "CHAP Coordinator exposed as MCP tools. Every tool call is recorded on the CHAP audit log; governed methods enforce membership and review rules server-side.",
+      instructions: "CHAP Coordinator exposed as MCP tools. Every accepted call that changes state is recorded on the CHAP audit log, as is a member's refused attempt at a governed action. Governed methods enforce membership and review rules server-side.",
       ttlMs: LIST_TTL_MS,
       cacheScope: "public",
       _meta: { [META_SERVER_INFO]: serverInfo }
@@ -981,6 +1093,7 @@ function dispatchToolCall(coord, toolName, args, envelopeId = "mcp-call") {
   SCHEMAS,
   SUPPORTED_PROTOCOL_VERSIONS,
   ServerDiscoverRequestSchema,
+  TOOL_ANNOTATIONS,
   TOOL_DESCRIPTIONS,
   TOOL_NAMES,
   UNSUPPORTED_PROTOCOL_VERSION,