@taiga-ai/mcp-server 0.16.0-rc.431 → 0.17.0-dev.439

package/src/tools/inbox.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
 import { OPERATE, READ_ONLY } from './annotations.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { pagination, productId } from './inputs.js';
+import { idInput, pagination, productId } from './inputs.js';
 import { page, pickFields } from './summarize.js';
 
 /**
@@ -19,6 +19,7 @@ type Row = Record<string, unknown>;
 const ITEM_FIELDS = [
   'id',
   'productId',
+  'productName',
   'category',
   'kind',
   'subjectType',
@@ -36,6 +37,7 @@ const ITEM_FIELDS = [
 const SETUP_TASK_FIELDS = [
   'id',
   'productId',
+  'productName',
   'category',
   'phase',
   'target',
@@ -61,7 +63,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'initiatives, a document, a pull request, maintenance findings, new policy violations), each a decision ' +
         'an agent handed back rather than made, and things to set up that only a person can (a secret, an ' +
         'environment variable, an account, a package registry, a cloud permission). Across every product the key ' +
-        'can open, or one product. category gate is the reviews, setup the setup items; resolved: true reads the ' +
+        'can open (each row names its product), or one product. category gate is the reviews, setup the setup items; resolved: true reads the ' +
         "archive of done and dismissed ones. The inbox is shared: it is the team's, not one person's. " +
         'An item snoozed until later is left out until then, as the page leaves it out (snoozedHidden counts ' +
         'them). taiga_list_setup_tasks has the setup tasks with what exactly to set.',
@@ -106,13 +108,20 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'not store or display), the provider page to do it on, and the phase that says when it blocks you ' +
         '(prereq: before the deploy, which fails without it; wiring: connecting generated values back to ' +
         'providers; followup: billing approvals, extra permissions and the like that can wait until after launch). ' +
-        'A build does not wait for any of them. Across every product the key can open, or one.',
-      inputSchema: z.object({ productId: productId.optional(), ...pagination }),
+        'A build does not wait for any of them. Across every product the key can open (each row names its ' +
+        'product), or one. The tasks still to do, oldest first, the order they depend on each other; ' +
+        'includeDone: true adds the done and dismissed ones.',
+      inputSchema: z.object({
+        productId: productId.optional(),
+        includeDone: z.boolean().optional().describe('Also the tasks already done or dismissed (default false)'),
+        ...pagination,
+      }),
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
-        const result = await client.listSetupTasks(params);
+        const { includeDone, ...rest } = params;
+        const result = await client.listSetupTasks({ ...rest, ...(includeDone ? {} : { openOnly: true }) });
         return toolResult(page(pickFields(result.data as Row[], SETUP_TASK_FIELDS), result.nextCursor));
       })
   );
@@ -133,7 +142,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
         'document was reviewed, and setting it back to in_progress withdraws that; do it only when the person ' +
         'says they read them. Ask the person before clearing what they have not dealt with.',
       inputSchema: z.object({
-        itemId: z.string().uuid().describe('Action Required item ID -- taiga_list_action_required gives it'),
+        itemId: idInput('Action Required item', 'taiga_list_action_required gives it'),
         status: z.enum(['in_progress', 'done', 'dismissed']).optional().describe('What became of it'),
         snoozedUntil: z
           .string()
@@ -147,7 +156,7 @@ export function registerInboxTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         if (params.status === undefined && params.snoozedUntil === undefined) {
-          return toolError('VALIDATION_FAILED', 'Say what became of the item (status) or until when to snooze it.');
+          return toolError('VALIDATION_ERROR', 'Say what became of the item (status) or until when to snooze it.');
         }
         const result = await client.updateInboxItem(params.itemId, {
           ...(params.status !== undefined ? { status: params.status } : {}),

package/src/tools/index.ts

@@ -18,10 +18,12 @@ import { registerQueueTools } from './queue.js';
 import { registerRepositoryTools } from './repositories.js';
 import { registerResources } from './resources.js';
 import { registerSetupTools } from './setup.js';
+import { notFoundHint, notFoundHints } from './hints.js';
 import { DEFAULT_WAIT_OPTIONS, registerWaitTools, type WaitOptions } from './wait.js';
 
 /**
- * Every tool refuses an argument it does not take. A plain object schema
+ * Every tool refuses an argument it does not take, and every tool's 404 says
+ * where the right IDs are (hints.ts). A plain object schema
  * strips one silently: a review note passed to a tool with no place for it
  * vanished and the call still succeeded, and a misspelt option quietly
  * became its default. Strict, the call fails with "Unrecognized key" and the
@@ -36,7 +38,11 @@ function withStrictInputs(server: McpServer): McpServer {
       throw new Error(`Tool ${name}: inputSchema must be a z.object() so unknown arguments can be refused`);
     }
     // .strict() keeps the object's own checks (a refine stays a refine).
-    return register(name, schema ? { ...config, inputSchema: schema.strict() } : config, callback);
+    // The call runs with its not-found hint in scope, for runTool to add to a 404.
+    const handler = callback as (args: unknown, ctx: unknown) => unknown;
+    const withHint = (args: unknown, ctx: unknown) =>
+      notFoundHints.run(notFoundHint(name, args), () => handler(args, ctx));
+    return register(name, schema ? { ...config, inputSchema: schema.strict() } : config, withHint);
   }) as unknown as McpServer['registerTool'];
   return server;
 }

package/src/tools/inputs.ts

@@ -2,10 +2,22 @@ import { z } from 'zod';
 
 /** The inputs several tools share, so a product or a page is named the same way everywhere. */
 
-export const productId = z
-  .string()
-  .uuid()
-  .describe('Product ID -- taiga_get_product_context, taiga_resolve_product or taiga_list_products give it');
+/**
+ * An ID input whose refusal says where the ID comes from. The client shows the
+ * schema's message, not the description, when a call fails validation, and
+ * "Invalid UUID" alone sends a model that passed a name to guess again.
+ */
+export function idInput(what: string, from: string) {
+  return z
+    .string()
+    .uuid({ message: `A ${what} ID is a UUID, not a name: ${from}` })
+    .describe(`${what[0]!.toUpperCase()}${what.slice(1)} ID -- ${from}`);
+}
+
+export const productId = idInput(
+  'product',
+  'taiga_list_products (query finds one by name), taiga_resolve_product or taiga_get_product_context give it'
+);
 
 /** The page inputs every list tool takes; `nextCursor` of one page is the `cursor` of the next. */
 export const pagination = {

package/src/tools/instructions.ts

@@ -7,15 +7,47 @@ import {
 } from './catalogue.js';
 
 /**
- * What the server tells a client at connect time: the knowledge base, the
- * order to read it in, the two document timelines, what section metadata
- * means, and when to write. Kept as data so a test can hold it to the
- * catalogue the same way it holds the tool descriptions.
+ * What the server tells a client at connect time: where to start, when to ask
+ * before writing, the words, then the knowledge base, the two document
+ * timelines, what section metadata means. Kept as data so a test can hold it
+ * to the catalogue the same way it holds the tool descriptions.
+ *
+ * The order is the point. Clients cut long instructions (Claude Code shows
+ * about the first 2,000 characters), so what an agent needs before its first
+ * call -- start with the context read, ask before paid or shared writes, what
+ * a refusal means, which word means what -- comes first, under
+ * INSTRUCTIONS_HEAD_LIMIT, and the reference material after it.
  */
-export const SERVER_INSTRUCTIONS = [
+export const INSTRUCTIONS_HEAD = [
   "You have access to Taiga, a policy-aware software development platform: the organization's",
   'engineering knowledge base, its products, their backlog and what the coding agent has built.',
   '',
+  '**Start here.** Call taiga_get_product_context first, naming the product by its git remote URL inside a',
+  'checkout (git remote get-url origin), else by slug or ID (taiga_list_products finds one by name with',
+  'query). It returns the product (and, while it is in setup, nextStep: what it waits for), its factory',
+  'instructions, its specification and architecture, every policy as its section ids, the open initiatives,',
+  'the repositories and the latest runs. Then read only what you need: the policy sections with',
+  'taiga_get_document, an initiative with taiga_get_backlog_item. Check Action Required',
+  '(taiga_list_action_required) for what waits on a person.',
+  '',
+  '**Before you write.** Tell the person what you are about to do and wait for their yes before a tool that',
+  'starts paid agent work (queueing, approving, resuming, requesting, importing, generating), interrupts it',
+  '(stopping, pausing) or changes what others read (publishing, resolving, settings, repositories). A client',
+  'that prompts on destructive tools does part of that for you.',
+  '',
+  '**Answers.** A refusal carries the API reason: say it as it is. NOT_FOUND names the tool that lists the',
+  'right IDs; an ID is a UUID, never a name. An empty result says why when it has a reason.',
+  '',
+  '**Words.** A backlog item is an initiative; a build is a run, the record of one attempt at it; Action',
+  'Required is the inbox; the line is the queue; a factory is the group that owns a set of products.',
+].join('\n');
+
+/** The most the head may take: under what a client shows before it cuts. */
+export const INSTRUCTIONS_HEAD_LIMIT = 1900;
+
+export const SERVER_INSTRUCTIONS = [
+  INSTRUCTIONS_HEAD,
+  '',
   '**Company documents** (taiga_list_documents / taiga_get_document):',
   `The ${POLICY_TYPES.length} policies (${named(POLICY_TYPES)}) carry the security, data, SDLC, operations and`,
   `architecture rules that apply to all code. The other documents (${named(OTHER_TENANT_DOCUMENT_TYPES)})`,
@@ -110,15 +142,9 @@ export const SERVER_INSTRUCTIONS = [
   '`priority: core` marks the sections every organization keeps. Neither changes what the section',
   'requires of you.',
   '',
-  'Workflow: start with taiga_get_product_context, naming the product by its git remote URL inside a checkout',
-  '(git remote get-url origin), else by slug or ID from taiga_list_products. It returns the product, the',
-  'factory instructions, the specification and architecture as the whole sections that fit (the rest named for',
-  'taiga_get_product_document to read by section), every policy as its section ids, the open backlog',
-  'items, the repositories and the latest runs in one call, and names any part it could not read. Then read',
-  'what you need in full: a policy with taiga_get_document, a backlog item with taiga_get_backlog_item.',
-  'Without it, use taiga_list_factories and taiga_list_products, then read the factory instructions,',
-  "the product's specification and architecture, and the backlog item you are working on. A document",
-  'read that finds nothing tells you what does exist and which tool reads or writes it.',
+  'Without taiga_get_product_context, use taiga_list_factories and taiga_list_products, then read the',
+  "factory instructions, the product's specification and architecture, and the initiative you are working",
+  'on. A document read that finds nothing tells you what does exist and which tool reads or writes it.',
   '',
   'The same documents are resources (taiga://documents/{type}, taiga://products/{productId}/documents/{type},',
   'taiga://factories/{factoryId}/instructions, taiga://backlog/{itemId}) for clients that attach them, and three',

package/src/tools/jobs.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/server';
 import { createdInitiativeIdsOf, createdInitiativesOf, isBacklogGenerationEmptyResult } from '@taiga/types';
 import { z } from 'zod';
+import { idInput } from './inputs.js';
 import type { TaigaClient } from '../client.js';
 import { READ_ONLY } from './annotations.js';
 import { runTool, toolResult } from './errors.js';
@@ -81,7 +82,7 @@ export function registerJobTools(server: McpServer, client: TaigaClient) {
         'added, or why it added none (already covered by an existing initiative, not readable as work, outside ' +
         'the product, or not allowed by a policy, with the policy, the line it runs into and the way to decide ' +
         'otherwise). taiga_wait_for_job waits for a job to finish.',
-      inputSchema: z.object({ jobId: z.string().uuid().describe('Agent job ID -- a request tool returns it') }),
+      inputSchema: z.object({ jobId: idInput('job', 'the tool that started the job returned it') }),
       annotations: READ_ONLY,
     },
     (params) => runTool(async () => toolResult(jobReport((await client.getAgentJob(params.jobId)).data as Row)))

package/src/tools/knowledge.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
 import { OPERATE, READ_ONLY } from './annotations.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { pagination } from './inputs.js';
+import { idInput, pagination, productId } from './inputs.js';
 import { page, pickFields } from './summarize.js';
 
 /**
@@ -34,11 +34,11 @@ const KNOWLEDGE_FIELDS = [
 /** Past this many characters a text file's content is cut when read; the download URL has it all. */
 const TEXT_LIMIT = 20_000;
 
-const knowledgeId = z.string().uuid().describe('Knowledge file ID -- taiga_list_knowledge gives it');
+const knowledgeId = idInput('knowledge file', 'taiga_list_knowledge gives it');
 
 const scopeInputs = {
-  factoryId: z.string().uuid().optional().describe("A factory's knowledge"),
-  productId: z.string().uuid().optional().describe("A product's knowledge"),
+  factoryId: idInput('factory', 'taiga_list_factories gives it').optional().describe("A factory's knowledge"),
+  productId: productId.optional().describe("A product's knowledge"),
 };
 
 /** Bytes of a text file the read takes at most; the download URL has the rest. */
@@ -113,7 +113,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const twoLevels = oneLevel(params);
-        if (twoLevels) return toolError('VALIDATION_FAILED', twoLevels);
+        if (twoLevels) return toolError('VALIDATION_ERROR', twoLevels);
         // One level at a time, as the page shows it: the route reads null as
         // "none at this level", so the organization's files are the ones with
         // no factory and no product, and a factory's the ones with no product.
@@ -200,7 +200,7 @@ export function registerKnowledgeTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const twoLevels = oneLevel(params);
-        if (twoLevels) return toolError('VALIDATION_FAILED', twoLevels);
+        if (twoLevels) return toolError('VALIDATION_ERROR', twoLevels);
         const mime = params.fileName.toLowerCase().endsWith('.md') ? 'text/markdown' : 'text/plain';
         const result = await client.addKnowledge({
           fileName: params.fileName,

package/src/tools/maintenance.ts

@@ -9,7 +9,7 @@ import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
 import { OPERATE, READ_ONLY } from './annotations.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { pagination, productId } from './inputs.js';
+import { idInput, pagination, productId } from './inputs.js';
 import { page, pickFields } from './summarize.js';
 
 /**
@@ -75,7 +75,7 @@ const VIOLATION_FIELDS = [
   'assessedAt',
 ] as const;
 
-const findingId = z.string().uuid().describe('Finding ID -- taiga_list_findings gives it');
+const findingId = idInput('finding', 'taiga_list_findings gives it');
 
 export function registerMaintenanceTools(server: McpServer, client: TaigaClient) {
   if (!client.hasCapability('products:read')) return;
@@ -100,7 +100,10 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
           client.listMaintenanceSweeps(params.productId, { limit: 3 }),
         ]);
         const latest = pickFields(sweeps.data as Row[], SWEEP_FIELDS);
-        const { lastRun: _lastRun, ...standing } = summary.data as Row;
+        // 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 as Row;
         return toolResult({
           ...standing,
           latestSweeps: latest,
@@ -167,7 +170,8 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
         "Where 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. A control with no violation ' +
+        'awaiting verification), and when the documents were derived and assessed, led by a summary of the ' +
+        'counts. A control with no violation ' +
         'is not listed, and it is not "passing" either: there is no such state. Pass full: true for every ' +
         "violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
       inputSchema: z.object({
@@ -182,23 +186,42 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     (params) =>
       runTool(async () => {
         const standing = (await client.getPolicyStanding(params.productId)).data as Row;
-        if (params.full) return toolResult(standing);
         const controls = Array.isArray(standing.controls) ? (standing.controls as Row[]) : [];
         const violations = Array.isArray(standing.divergences) ? (standing.divergences as Row[]) : [];
         const resolved = Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences.length : 0;
+        const listed = controls.filter((c) => Number(c.divergenceCount ?? 0) > 0 || Number(c.findingCount ?? 0) > 0);
+        const bySeverity: Record<string, number> = {};
+        for (const violation of violations) {
+          const severity = String(violation.severity ?? 'unknown');
+          bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
+        }
+        // The counts first, on both answers: the lists run to thousands of
+        // tokens, and "how bad is it" is the first question.
+        const summary = {
+          controls: listed.length,
+          violations: violations.length,
+          bySeverity,
+          resolvedViolations: resolved,
+        };
+        if (params.full) return toolResult({ summary, ...standing });
         return toolResult({
+          summary,
           productId: standing.productId,
           hasPolicies: standing.hasPolicies,
           assessment: standing.assessment,
           documents: standing.documents,
           // Only the controls something is recorded against; every other
           // control is simply not reported, as the page does.
-          controls: pickFields(
-            controls.filter((c) => Number(c.divergenceCount ?? 0) > 0 || Number(c.findingCount ?? 0) > 0),
-            ['controlId', 'policyType', 'text', 'state', 'divergenceCount', 'findingCount', 'plannedCount']
-          ),
+          controls: pickFields(listed, [
+            'controlId',
+            'policyType',
+            'text',
+            'state',
+            'divergenceCount',
+            'findingCount',
+            'plannedCount',
+          ]),
           violations: pickFields(violations, VIOLATION_FIELDS),
-          resolvedViolations: resolved,
         });
       })
   );
@@ -233,7 +256,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
     (params) =>
       runTool(async () => {
         if (params.ignored && params.reason === undefined) {
-          return toolError('VALIDATION_FAILED', 'Say why the finding is ignored (reason).');
+          return toolError('VALIDATION_ERROR', 'Say why the finding is ignored (reason).');
         }
         const body = params.ignored
           ? {
@@ -315,7 +338,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
       inputSchema: z.object({
         productId,
         controlId: z.string().min(1).max(40).optional().describe("The control's identifier, e.g. SEC-3.4"),
-        violationId: z.string().uuid().optional().describe('One violation -- taiga_get_policy_standing gives it'),
+        violationId: idInput('violation', 'taiga_get_policy_standing gives it').optional(),
       }),
       annotations: OPERATE,
     },
@@ -323,7 +346,7 @@ export function registerMaintenanceTools(server: McpServer, client: TaigaClient)
       runTool(async () => {
         if ((params.controlId === undefined) === (params.violationId === undefined)) {
           return toolError(
-            'VALIDATION_FAILED',
+            'VALIDATION_ERROR',
             'Name either a control (controlId) or one violation (violationId), not both or neither.'
           );
         }

package/src/tools/observe.ts

@@ -4,7 +4,8 @@ import { z } from 'zod';
 import { TaigaApiError, type TaigaClient } from '../client.js';
 import { OPERATE, OPERATE_SETTING, READ_ONLY } from './annotations.js';
 import { isNetworkFailure, runTool, toolError, toolResult } from './errors.js';
-import { pagination, productId } from './inputs.js';
+import { withNotFoundHint } from './hints.js';
+import { idInput, pagination, productId } from './inputs.js';
 import { page, pickFields } from './summarize.js';
 
 /**
@@ -38,7 +39,7 @@ const DEPLOYMENT_FIELDS = [
 
 const ENVIRONMENT_FIELDS = ['id', 'name', 'slug', 'type', 'ordinal', 'status', 'isProtected', 'url'] as const;
 
-const environmentId = z.string().uuid().describe('Environment ID -- taiga_get_deployments lists them');
+const environmentId = idInput('environment', 'taiga_get_deployments lists them; a product ID is not one');
 const windowDays = (choices: string) =>
   z.number().int().optional().describe(`Days to look back: ${choices} (default 30)`);
 
@@ -104,6 +105,16 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
           part(() => client.getDeploymentSyncStatus(params.productId)),
         ]);
         const now = current.data as { current?: Row[]; deploying?: Row[] };
+        // An empty answer says why, as the maintenance read does: no
+        // 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, ' +
+              'and its deployments are mirrored from the provider once it is.'
+            : (history.data as Row[]).length === 0 && !params.cursor
+              ? 'No deployments recorded yet: none was mirrored from the provider (syncStatus says when it last ' +
+                'synced), or nothing has been deployed.'
+              : null;
         return toolResult({
           environments: pickFields(environments.rows, ENVIRONMENT_FIELDS),
           ...(environments.more ? { moreEnvironments: true } : {}),
@@ -113,6 +124,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
           ...('value' in sync
             ? { syncStatus: sync.value.data }
             : { syncStatus: null, syncUnavailable: sync.unavailable }),
+          ...(note ? { note } : {}),
         });
       })
   );
@@ -136,7 +148,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
       runTool(async () => {
         const days = params.windowDays ?? 30;
         if (![30, 60, 90].includes(days)) {
-          return toolError('VALIDATION_FAILED', 'windowDays is 30, 60 or 90.');
+          return toolError('VALIDATION_ERROR', 'windowDays is 30, 60 or 90.');
         }
         return toolResult((await client.getDeliveryMetrics(params.productId, params.environmentId, days)).data);
       })
@@ -164,10 +176,21 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
     (params) =>
       runTool(async () => {
         const health = await client.getMonitoringHealth(params.productId);
-        if (!params.environmentId) return toolResult({ health: health.data });
+        if (!params.environmentId) {
+          return toolResult({
+            health: health.data,
+            ...(health.data.length === 0
+              ? {
+                  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.',
+                }
+              : {}),
+          });
+        }
         const days = params.windowDays ?? 30;
         if (![30, 60, 90].includes(days)) {
-          return toolError('VALIDATION_FAILED', 'windowDays is 30, 60 or 90, the windows the page offers.');
+          return toolError('VALIDATION_ERROR', 'windowDays is 30, 60 or 90, the windows the page offers.');
         }
         const env = params.environmentId;
         const [uptime, experience, clientHealth] = await Promise.all([
@@ -175,10 +198,28 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
           part(() => client.getMonitoringSignal(params.productId, 'rum', env, days)),
           part(() => client.getMonitoringSignal(params.productId, 'client-health', env, days)),
         ]);
+        // The API refuses an environment that is not the product's with 404
+        // on every signal: that is a wrong ID, not three signals missing.
+        if (
+          'unavailable' in uptime &&
+          [uptime, experience, clientHealth].every((p) => 'unavailable' in p && p.unavailable.startsWith('404'))
+        ) {
+          // The API's own word, with the environmentId hint, as runTool gives any 404.
+          const said = uptime.unavailable.replace(/^404:\s*/, '') || 'Environment not found';
+          return toolError('NOT_FOUND', withNotFoundHint(said));
+        }
         const value = (p: { value: { data: unknown } } | { unavailable: string }) =>
           'value' in p ? p.value.data : { unavailable: p.unavailable };
+        const envHealth = (health.data as Row[]).filter((row) => row.environmentId === env);
         return toolResult({
-          health: (health.data as Row[]).filter((row) => row.environmentId === env),
+          health: envHealth,
+          ...(envHealth.length === 0
+            ? {
+                note:
+                  'No health for this environment: it has no App URL to check yet (taiga_update_environment ' +
+                  'sets one). No health is not good health.',
+              }
+            : {}),
           windowDays: days,
           uptime: value(uptime),
           realUserExperience: value(experience),
@@ -236,7 +277,7 @@ export function registerObserveTools(server: McpServer, client: TaigaClient) {
       runTool(async () => {
         const { environmentId: id, ...changes } = params;
         if (Object.values(changes).every((value) => value === undefined)) {
-          return toolError('VALIDATION_FAILED', 'Change at least one of name, type or url.');
+          return toolError('VALIDATION_ERROR', 'Change at least one of name, type or url.');
         }
         const updated = (await client.updateEnvironment(id, changes)).data as Row;
         return toolResult(pickFields([updated], ENVIRONMENT_FIELDS)[0]);