@taiga-ai/mcp-server 0.20.0-dev.454 → 0.21.0-dev.455

package/src/tools/maintenance.ts

@@ -6,9 +6,9 @@ import {
   MAINTENANCE_IGNORE_REASONS,
 } from '@taiga/types';
 import { z } from 'zod';
-import type { TaigaClient } from '../client.js';
+import { TaigaApiError, type TaigaClient } from '../client.js';
 import { OPERATE, READ_ONLY } from './annotations.js';
-import { runTool, toolError, toolResult } from './errors.js';
+import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
 import { idInput, pagination, productId } from './inputs.js';
 import { page, pickFields } from './summarize.js';
 
@@ -75,6 +75,24 @@ const VIOLATION_FIELDS = [
 
 type Row = Record<string, unknown>;
 
+/** Characters of one text field the full standing carries; violationId reads one violation uncut. */
+const FULL_TEXT_LIMIT = 1_500;
+
+/** Resolved violations the full standing carries. */
+const FULL_RESOLVED = 20;
+
+/** A copy with every string longer than the limit cut and marked, at any depth. */
+function cutLongText(value: unknown): unknown {
+  if (typeof value === 'string') {
+    return value.length > FULL_TEXT_LIMIT
+      ? `${value.slice(0, FULL_TEXT_LIMIT)}... [cut at ${FULL_TEXT_LIMIT} of ${value.length} characters; violationId reads it whole]`
+      : value;
+  }
+  if (Array.isArray(value)) return value.map(cutLongText);
+  if (value === null || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, cutLongText(inner)]));
+}
+
 /**
  * How bad a product's policy standing is, as counts: the controls something is
  * recorded against, the open violations by severity, the resolved ones. The
@@ -116,55 +134,41 @@ export function standingSummary(standing: {
 
 const findingId = idInput('finding', 'taiga_list_findings gives it');
 
+/** Open findings by severity and kind, and the latest sweeps, as the first page of findings carries them. */
+async function sweepOverview(client: TaigaClient, productId: string) {
+  const [summary, sweeps] = await Promise.all([
+    client.getMaintenanceSummary(productId),
+    client.listMaintenanceSweeps(productId, { limit: 3 }),
+  ]);
+  const latest = pickFields(sweeps.data, SWEEP_FIELDS);
+  // The summary's own run rows (one per repository) would repeat the sweeps with every column.
+  const {
+    lastRun: _lastRun,
+    lastRuns: _lastRuns,
+    topFindings: _top,
+    violatedControls: _controls,
+    ...counts
+  } = summary.data as Record<string, unknown>;
+  return {
+    ...counts,
+    latestSweeps: latest,
+    ...(latest.length === 0 ? { note: 'This product has never been swept: no findings is not an all-clear.' } : {}),
+  };
+}
+
 export function registerMaintenanceTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
 
-  server.registerTool(
-    'taiga_get_maintenance',
-    {
-      title: "Get a product's maintenance standing",
-      description:
-        "Where a product's repository stands: open findings by severity and kind, the most pressing ones, and " +
-        'the latest sweeps, so you can tell when the product was last checked and whether that check succeeded. A ' +
-        'quiet list from a sweep that last ran long ago, or that failed, is not an all-clear; a product never swept ' +
-        'says so. Sweeps run on their own after a push and periodically; nothing here starts one. This is the ' +
-        'overview of the scanners alone; taiga_list_findings lists each finding to act on, and ' +
-        'taiga_get_policy_standing judges the product against the policies (scanner findings and the documents).',
-      inputSchema: z.object({ productId }),
-      annotations: READ_ONLY,
-    },
-    (params) =>
-      runTool(async () => {
-        const [summary, sweeps] = await Promise.all([
-          client.getMaintenanceSummary(params.productId),
-          client.listMaintenanceSweeps(params.productId, { limit: 3 }),
-        ]);
-        const latest = pickFields(sweeps.data, SWEEP_FIELDS);
-        // The sweeps are reported as `latestSweeps`, narrowed to SWEEP_FIELDS;
-        // the summary's own run rows (PRO-2527: one per repository) would
-        // repeat them with every column.
-        const { lastRun: _lastRun, lastRuns: _lastRuns, ...standing } = summary.data;
-        return toolResult({
-          ...standing,
-          latestSweeps: latest,
-          ...(latest.length === 0 ? { note: 'This product has never been swept: no result is not an all-clear.' } : {}),
-        });
-      })
-  );
-
   server.registerTool(
     'taiga_list_findings',
     {
       title: 'List maintenance findings',
       description:
-        "List what the sweeps found in a product's repository: vulnerable or outdated dependencies, committed " +
-        'secrets, insecure code (sast) and infrastructure misconfigurations (iac_misconfig). Each row carries its ' +
-        'severity and its priority tier (act_now: known exploited; urgent: likely and serious; elevated: one of ' +
-        'the two; routine), where it is, who can fix it (remediableBy: coding_agent, or upstream_only for a ' +
-        'submodule or a dependency with no fixed version), the policy controls it breaches, and the initiative ' +
-        'already fixing it (initiativeId). Omit status for the findings that need action; work from the top tier ' +
-        'down. Read one in full with taiga_get_finding. taiga_get_maintenance has the counts and when the last ' +
-        'sweep ran, which says whether an empty list can be trusted.',
+        "List what maintenance sweeps found in a product's repository: dependencies, secrets, insecure code " +
+        '(sast) and infrastructure. The first page opens with sweep (open counts, latest sweeps), so an old or ' +
+        'failed sweep is not read as an all-clear. Rows: severity, tier (act_now: known exploited; urgent: ' +
+        'likely and serious; elevated: one of the two; routine), location, remediableBy (upstream_only: no fixed ' +
+        'version), breached controls and initiativeId of a fix under way. Omit status for open findings. taiga_get_finding reads one.',
       inputSchema: z.object({
         productId,
         status: z
@@ -180,8 +184,28 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     (params) =>
       runTool(async () => {
         const { productId: id, ...filters } = params;
-        const result = await client.listFindings(id, filters);
+        // The sweep overview on the first page: when the product was last
+        // checked decides whether an empty list can be trusted.
+        const [result, sweep] = await Promise.all([
+          client.listFindings(id, filters),
+          // Best effort: the findings the agent asked for do not fail on the overview.
+          params.cursor === undefined
+            ? sweepOverview(client, id).catch((error: unknown) => {
+                if (error instanceof TaigaApiError || isNetworkFailure(error)) return 'unread' as const;
+                throw error;
+              })
+            : Promise.resolve(null),
+        ]);
         return toolResult({
+          // An overview that could not be read says so: without it an empty list would read as an all-clear.
+          ...(sweep === 'unread'
+            ? {
+                sweep: null,
+                sweepNote: 'The sweep overview could not be read: an empty list here is not an all-clear.',
+              }
+            : sweep
+              ? { sweep }
+              : {}),
           ...page(pickFields(result.data, FINDING_ROW_FIELDS), result.nextCursor),
           ...(typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {}),
         });
@@ -193,10 +217,10 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Get a maintenance finding',
       description:
-        'Read one maintenance finding in full: what it is, how likely it is to be exploited (EPSS, the known-exploited list), ' +
-        'the advisory and the fixed version, the place in the code, the policy controls it breaches, why it is ' +
-        'ranked where it is, its history (reintroduced, previously resolved) and the remediation under way. A ' +
-        "secret's value is never stored; the finding names the rule and the location only.",
+        'Read one maintenance finding in full: exploit likelihood (EPSS, known-exploited list), advisory and ' +
+        'fixed version, code location, breached policy controls, why it ranks where it does, history ' +
+        "(reintroduced, previously resolved) and the remediation under way. A secret's value is never stored, " +
+        'only the rule and location.',
       inputSchema: z.object({ findingId }),
       annotations: READ_ONLY,
     },
@@ -214,24 +238,24 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: "Get a product's policy standing",
       description:
-        "How a product stands against the organization's own published policies: the controls it violates, " +
-        "each with its violations (critical and high only, each citing the policy's sentence and the document " +
-        'passage that contradicts it), what is being done about each (an initiative raised, a fix in progress, ' +
-        'awaiting verification), and when the documents were derived and assessed, led by a summary of the ' +
-        'counts. A control is breached when open scanner findings map to it, diverged when the assessment of the ' +
-        'product documents found them contradicting it (a control can be both; state names the stronger, ' +
-        "breached). A violation's work is the initiative raised for it; live: false means that initiative is " +
-        'done or canceled without the violation going away, so it needs a person or a new fix. A control ' +
-        'breached by scanner findings counts them by tier (findingsByTier): a breach of ' +
-        'routine findings only, such as secrets in test fixtures, is not an urgent one. A control with no violation ' +
-        'is not listed, and it is not "passing" either: there is no such state; summary.controlsWithNothingRecorded counts them. Pass full: true for every ' +
-        "violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
+        "How a product stands against the organization's published policies: summary counts, when the documents " +
+        'were assessed, and each violated control with its violations (critical and high only, citing the policy ' +
+        'sentence and the contradicting passage) and the work on each. state: breached (open scanner findings ' +
+        'map to it, by findingsByTier; routine-only is not urgent) or diverged (the documents contradict it). ' +
+        "live: false means the violation's initiative ended without fixing it: it needs a person or a new fix. " +
+        'An unlisted control is not "passing" (summary.controlsWithNothingRecorded counts them). full: true adds ' +
+        'evidence and resolved ones. Fix with taiga_fix_policy_violation.',
       inputSchema: z.object({
         productId,
         full: z
           .boolean()
           .optional()
-          .describe("Carry each violation's evidence, the policy excerpt and the resolved violations (default false)"),
+          .describe(
+            "Carry each violation's evidence and policy excerpt, cut to about 1,500 characters each, and up to 20 resolved violations (default false)"
+          ),
+        violationId: idInput('violation', 'this tool lists them')
+          .optional()
+          .describe('Only this violation, in full and uncut: its evidence, policy excerpt and work'),
       }),
       annotations: READ_ONLY,
     },
@@ -252,7 +276,36 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
               'all-clear. An assessment runs when the reality documents are derived or refreshed ' +
               '(taiga_refresh_reality_documents, paid work: ask first).'
             : null;
-        if (params.full) return toolResult({ summary, ...(note ? { note } : {}), ...standing });
+        if (params.violationId) {
+          const one = [
+            ...violations,
+            ...(Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences : []),
+          ].find((violation) => (violation as Row)['id'] === params.violationId);
+          if (!one) {
+            return toolError(
+              'NOT_FOUND',
+              'No violation with that ID on this product; this tool without violationId lists them.'
+            );
+          }
+          return toolResult(one);
+        }
+        // The full form ran to 228k characters on a product with eleven violations (PRO-2800): each text is
+        // cut and the resolved list bounded; violationId reads one whole.
+        if (params.full) {
+          const resolvedAll = Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences : [];
+          return toolResult({
+            summary,
+            ...(note ? { note } : {}),
+            ...standing,
+            // Only the controls something is recorded against, as the summary answer lists them.
+            controls: listed,
+            divergences: cutLongText(violations),
+            resolvedDivergences: cutLongText(resolvedAll.slice(0, FULL_RESOLVED)),
+            ...(resolvedAll.length > FULL_RESOLVED
+              ? { resolvedNote: `The first ${FULL_RESOLVED} of ${resolvedAll.length} resolved violations.` }
+              : {}),
+          });
+        }
         return toolResult({
           summary,
           ...(note ? { note } : {}),
@@ -284,13 +337,11 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Ignore or reopen a finding',
       description:
-        'Ignore a maintenance finding, with a reason, or reopen it. Ignore one that does not apply or whose risk is accepted, with the reason (false_positive, ' +
-        'not_reachable, accepted_risk, wont_fix), an optional note and an optional expiry after which it resurfaces ' +
-        'if it still exists; or reopen an ignored one (ignored: false). Ignored findings are kept and reviewable. ' +
-        'There is no "mark fixed": a finding resolves when the next sweep no longer detects it. For a secret that ' +
-        'is only in history, rotate the credential outside Taiga, then ignore it with a reason. Ignoring hides a ' +
-        "shared signal and can record the team's acceptance of a risk, which is the person's decision: ask the " +
-        'person first.',
+        'Ignore a maintenance finding with a reason, or reopen one (ignored: false). Reasons: false_positive, ' +
+        'not_reachable, accepted_risk, wont_fix; plus an optional note and an expiry after which it resurfaces ' +
+        'if still present. There is no "mark fixed": a finding resolves when the next sweep stops detecting it. ' +
+        'For a secret only in history, rotate it outside Taiga, then ignore it. Ignoring can record the team ' +
+        "accepting a risk, which is the person's decision: ask first.",
       inputSchema: z.object({
         findingId,
         ignored: z.boolean().describe('true ignores the finding, false reopens it'),
@@ -327,14 +378,11 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Fix a finding',
       description:
-        "Ask Taiga to fix a maintenance finding: it raises an initiative and adds it to the end of the product's queue, where " +
-        "the line plans it in turn; whether the build then waits for a person is the initiative's review gate, " +
-        'as for any initiative. The fix is a normal run that ends in a pull request you review and merge. With ' +
-        "wholeGroup: true it fixes the finding's whole group in one initiative, as the page does: for a " +
-        'dependency, every open advisory on that package at that installed version in one version bump; for ' +
-        'code or infrastructure, every location the same rule flagged. Absent for a secret only in history, ' +
-        'anything in a submodule, and a dependency with no fixed version (remediableBy says upstream_only); the ' +
-        'API refuses those. Starts paid work.',
+        "Raise an initiative that fixes a maintenance finding, at the end of the product's line; it ends in a " +
+        "pull request a person merges, and the initiative's review gate applies. wholeGroup: true fixes the " +
+        'group in one initiative: every open advisory on that package version in one bump, or every location the ' +
+        'same rule flagged. Refused for a secret only in history, anything in a submodule, and remediableBy ' +
+        'upstream_only.',
       inputSchema: z.object({
         productId,
         findingId,
@@ -378,11 +426,10 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     {
       title: 'Fix policy violations',
       description:
-        "Ask Taiga to fix a product's policy violations (it raises initiatives): name a control to cover every violation recorded " +
-        'against it that has no initiative yet, or a single violation (violationId) when the control has more ' +
-        "than one. Taiga raises one initiative and adds it to the end of the product's queue, exactly as a " +
-        'finding fix does. The violation stays listed while the work is under way: only the next assessment ' +
-        'can record that the documents no longer show it. Starts paid work.',
+        "Raise one initiative that fixes a product's policy violations and add it to the end of the line. Name a " +
+        'control to cover all its violations with no initiative yet, or one violationId when the control has ' +
+        'several. The violation stays listed until the next assessment no longer finds it, even while the fix is ' +
+        'under way.',
       inputSchema: z.object({
         productId,
         controlId: z.string().min(1).max(40).optional().describe("The control's identifier, e.g. SEC-3.4"),

package/src/tools/observe.ts

@@ -100,13 +100,11 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get what runs where',
       description:
-        "What runs in each of a product's environments, and recent deployments: what is running now, anything deploying, and the recent " +
-        'history, newest first: each deployment with its commit, pull request, status, who deployed it and, ' +
-        'for a failure, the error the provider reported. What runs is the most recent deployment that actually ' +
-        'succeeded, so a newer failed attempt shows beside the version still running, not in its place. The ' +
-        'history is mirrored from the provider, including deployments made outside Taiga; syncStatus says when ' +
-        "it last synced. Pass environmentId for one environment's history. Taiga observes deployments and " +
-        'never performs them.',
+        "Read what runs in each of a product's environments and its recent deployments, newest first: commit, " +
+        "pull request, status, deployer and, on failure, the provider's error. What runs is the latest " +
+        'successful deployment, so a newer failure shows beside it. History is mirrored from the provider, ' +
+        'including deployments made outside Taiga; syncStatus says when it last synced. environmentId narrows to ' +
+        'one environment. Taiga never deploys.',
       inputSchema: z.object({ productId, environmentId: environmentId.optional(), ...pagination }),
       annotations: READ_ONLY,
     },
@@ -127,7 +125,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
         // environment, or none deployed to yet, is not "nothing is wrong".
         const note =
           environments.rows.length === 0
-            ? 'This product has no environments yet: an environment is defined with taiga_define_environment, ' +
+            ? 'This product has no environments yet: an environment is defined with taiga_create_environment, ' +
               'and its deployments are mirrored from the provider once it is.'
             : history.data.length === 0 && !params.cursor
               ? 'No deployments recorded yet: none was mirrored from the provider (syncStatus says when it last ' +
@@ -152,9 +150,9 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: "List a product's environments",
       description:
-        "The places a product's software runs (development, staging, production or its own ladder), each with " +
-        'its ID, type, order and App URL. The environment IDs taiga_get_delivery_metrics, taiga_get_monitoring ' +
-        'and taiga_update_environment take. taiga_get_deployments lists them too, beside what runs where.',
+        "List a product's environments with ID, type, order and App URL. These are the environment IDs " +
+        'taiga_get_delivery_metrics, taiga_get_monitoring and taiga_update_environment take. ' +
+        'taiga_get_deployments lists them too, with what runs where.',
       inputSchema: z.object({ productId }),
       annotations: READ_ONLY,
     },
@@ -164,7 +162,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
         return toolResult({
           data: pickFields(rows, ENVIRONMENT_FIELDS),
           ...(more ? { more: 'More environments than this answer reads; the rest were left out.' } : {}),
-          ...(rows.length === 0 ? { note: 'No environment is defined yet; taiga_define_environment adds one.' } : {}),
+          ...(rows.length === 0 ? { note: 'No environment is defined yet; taiga_create_environment adds one.' } : {}),
         });
       })
   );
@@ -174,13 +172,11 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Get delivery metrics',
       description:
-        "DORA's five delivery metrics for one environment (the one marked production, as the page " +
-        'reports them), computed from its deployment history over the last 30, 60 or 90 days: deployment ' +
-        'frequency, lead time and failed deployment recovery time (throughput), change-failure rate and rework ' +
-        'rate (instability), each with its trend against the window before, and a performance band for all but ' +
-        'rework rate, which DORA has published none for. Failures and recoveries are read from deployments, not ' +
-        'incidents. A trend built on fewer than ten deployments is approximate; a metric no deployment fed says ' +
-        'so instead of showing a number. Previews and checks do not count.',
+        "Read DORA's five delivery metrics for one environment (the page shows production) over 30, 60 or 90 " +
+        'days: deployment frequency, lead time, failed deployment recovery time, change-failure rate and rework ' +
+        'rate, each with its trend against the window before and a performance band (none for rework rate). ' +
+        'Computed from deployments, not incidents; previews and checks do not count. Under ten deployments a ' +
+        'trend is approximate; a metric with no data says so instead of a number.',
       inputSchema: z.object({ productId, environmentId, windowDays }),
       annotations: READ_ONLY,
     },
@@ -196,13 +192,11 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: "Get a product's monitoring",
       description:
-        "How a product's environments are doing (health, uptime): each environment's current health from Taiga's availability " +
-        'checks of its App URL, with its uptime and when it was last checked; a status Taiga cannot verify now ' +
-        'reads as not checked rather than the last thing it knew, and a new environment as baseline learning. ' +
-        "With environmentId, that environment's uptime over a 30, 60 or 90-day window, and the experience " +
-        'signals the beacon reports (Core Web Vitals, JavaScript errors, client-observed API health) where it is ' +
-        'installed; until then they read as not set up, which means no data, not good data. Setting up the ' +
-        "beacon raises an initiative from the environment's settings in the web.",
+        "How a product's environments are doing: each one's health from Taiga's checks of its App URL, uptime " +
+        'and last check (not checked when unverifiable now, baseline learning when new). With environmentId: ' +
+        'uptime over 30, 60 or 90 days and the beacon signals (Core Web Vitals, JavaScript errors, API health); ' +
+        "not set up means no data. Setting up the beacon raises an initiative from the environment's settings in " +
+        'the web.',
       inputSchema: z.object({
         productId,
         environmentId: environmentId.optional(),
@@ -220,7 +214,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
               ? {
                   note:
                     'No environment is monitored: monitoring starts when an environment has its App URL ' +
-                    '(taiga_define_environment, taiga_update_environment). No health is not good health.',
+                    '(taiga_create_environment, taiga_update_environment). No health is not good health.',
                 }
               : {}),
           });
@@ -265,16 +259,14 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:write')) return;
 
   server.registerTool(
-    'taiga_define_environment',
+    'taiga_create_environment',
     {
-      title: 'Define an environment',
+      title: 'Create an environment',
       description:
-        "Add a place a product's software runs: development, staging, production or whatever ladder it uses. " +
-        'Deployments are recorded against an environment, monitoring is reported per environment, and plans ' +
-        'read where the work will run. Describing one gives Taiga no access to it: the pipeline deploys, Taiga ' +
-        'learns what happened from source control. Member-level work. Give it its App URL afterwards with ' +
-        'taiga_update_environment, which is all monitoring needs to start checking. Changes the ' +
-        "product's setup for everybody.",
+        "Add an environment a product's software runs in (development, staging, production or its own). " +
+        'Deployments, monitoring and plans are tracked per environment. Taiga gets no access to it: the pipeline ' +
+        'deploys and Taiga learns what happened from source control. Members can do this. Then set its App URL ' +
+        "with taiga_update_environment so monitoring starts. Changes the product's setup for everybody.",
       inputSchema: z.object({
         productId,
         name: z.string().trim().min(1).max(100).describe('What the team calls it, e.g. staging'),
@@ -295,10 +287,9 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     {
       title: 'Update an environment',
       description:
-        'Rename an environment, change its kind, or set its public App URL (null clears it). The App URL is all ' +
-        "monitoring needs: once it is saved, Taiga checks the app's availability every few minutes on its own. " +
-        'Marking an environment production makes it the one delivery metrics report on. Changes the ' +
-        "product's setup for everybody.",
+        'Rename an environment, change its kind, or set its public App URL (null clears it). Once an App URL is ' +
+        'saved, Taiga checks availability every few minutes. Marking one production makes it the one delivery ' +
+        "metrics report on. Changes the product's setup for everybody.",
       inputSchema: z.object({
         environmentId,
         name: z.string().trim().min(1).max(100).optional().describe('A new name'),

package/src/tools/product-documents.ts

@@ -65,11 +65,10 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
       {
         title: 'Update a section of a product document draft',
         description:
-          'Replace the text of one section of a product document on its plan timeline, in the draft. Every other ' +
-          'section stays as it is. A draft changes nothing downstream: agents keep reading the published version ' +
-          'until the draft is published (taiga_publish_product_document). Refused once Discovery is finished and ' +
-          'the set is locked: reopening Discovery is done in the web. Reality documents are derived from the code ' +
-          'and not edited.',
+          "Replace one section's text in a plan-timeline product document's draft; other sections stay. Agents " +
+          'read the published version until taiga_publish_product_document. Refused once Discovery is finished and ' +
+          'the set is locked (reopen it with taiga_reopen_discovery or in the web). Reality documents come from ' +
+          'the code and are not edited.',
         inputSchema: z.object({
           productId,
           type: documentType,
@@ -91,9 +90,8 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
       title: 'Publish a product document draft',
       description:
         "Publish a product document's draft as its new version, the one agents work from. Documents generated " +
-        'from it are not rewritten: each is marked outdated, and is regenerated when someone chooses to ' +
-        '(taiga_regenerate_product_document, or taiga_generate_product_documents for every outdated and missing ' +
-        'one).',
+        'from it are marked outdated, not rewritten; regenerate them with taiga_regenerate_product_document, or ' +
+        'taiga_generate_product_documents for every outdated and missing one.',
       inputSchema: z.object({ productId, type: documentType }),
       annotations: OPERATE,
     },
@@ -105,10 +103,9 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
     {
       title: 'Mark a product document reviewed',
       description:
-        'Record that a person reviewed a product document: its latest published version, as the Documents page ' +
-        "shows it beside each version; once every published document is reviewed, the product's review item in " +
-        'Action Required resolves. The mark says a human read it, so make it only when the person tells you they ' +
-        'have: reading it yourself is not a review.',
+        "Record that a person reviewed a product document's latest published version. Once every published " +
+        "document is reviewed, the product's review item in Action Required resolves. Only when the person says " +
+        'they read it; your own reading is not a review.',
       inputSchema: z.object({ productId, type: reviewableType }),
       annotations: OPERATE,
     },
@@ -122,13 +119,11 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
       {
         title: 'Regenerate a product document',
         description:
-          'Ask an agent to generate one product document again from the documents it is derived from, for one ' +
-          'marked outdated or one that needs another pass. The Specification comes from the Discovery ' +
-          'conversation and the Look & Feel from its concepts, both in the web. The documents Discovery requires ' +
-          'are regenerated while it is open only: a finished Discovery locks them, and reopening it is done in ' +
-          'the web. The optional Service Blueprint can be generated whenever someone wants one. The result is published as the new version, and ' +
-          'the documents generated from it are marked outdated in turn. Runs an agent in the background: this ' +
-          'returns the job; taiga_wait_for_job says when it is done.',
+          'Regenerate one product document from the documents it derives from, when it is outdated or needs ' +
+          'another pass, and return the job. The result is published and documents derived from it are marked ' +
+          'outdated. The Specification (from the Discovery conversation) and the Look & Feel (from its concepts) ' +
+          'are made in the web. Documents Discovery requires regenerate only while Discovery is open; the optional ' +
+          'Service Blueprint any time. taiga_wait_for_job says when it is done.',
         inputSchema: z.object({ productId, type: generatedType }),
         annotations: OPERATE,
       },
@@ -164,11 +159,10 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
     {
       title: 'Generate the remaining product documents',
       description:
-        'Generate remaining: every document the product still needs, and every one marked outdated, in the ' +
-        'order they build on each other, one after another (each next one starts when the one before it is ' +
-        'published). Refused (CONFLICT) while a document is already being generated. On an imported product, ' +
-        'it queues every unpublished document. Runs agents in the background: this returns the jobs it started ' +
-        '(jobIds); taiga_stop_generating_documents stops the run.',
+        'Generate every missing or outdated product document (Generate remaining in the web), one after another ' +
+        'in the order they build on each other; on an imported product, every unpublished one. Returns the jobs ' +
+        'it started (jobIds). Refused (CONFLICT) while a document is already being generated. ' +
+        'taiga_stop_generating_documents stops it.',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },
@@ -180,8 +174,8 @@ export function registerProductDocumentWrites(server: McpServer, client: TaigaCl
     {
       title: 'Stop generating product documents',
       description:
-        'Stop a Generate remaining run: every document of it still being generated is cancelled and nothing ' +
-        'after them starts; published documents stay. An empty list means no run was going. Interrupts agent work.',
+        'Stop a Generate remaining run (taiga_generate_product_documents): documents still being generated are ' +
+        'cancelled and nothing after them starts; published ones stay. An empty list means none was running.',
       inputSchema: z.object({ productId }),
       annotations: OPERATE,
     },