@jrpool/kilotest 59.0.2 → 59.1.0

package/README.md

@@ -10,7 +10,7 @@ An ensemble testing and reporting service for front-end web quality
 
 ## Features
 
-This application uses an ensemble of 12 rule engines to test web pages for front-end quality (i.e. accessibility, usability, and standards conformity).
+This application uses an ensemble of 12 rule engines to test web pages for front-end quality (i.e. accessibility, usability, and web standards).
 
 The testing paradigm employed by Kilotest is discussed in these papers:
 
@@ -40,7 +40,7 @@ In the steps below, hosts `T` and `K` may be the same host or two different host
 
 ### Usage
 
-1. In the `testaro` directory, make Testaro start listening for jobs: `node call netWatch true nn true`, where `nn` is the number of seconds to wait between checks for new jobs. Note that Kilotest promises nearly immediate review and, on approval, immediate execution of “orders” for tests and retests, with typical total elapsed time about 2 minutes. That promise implies a promise to keep `nn` small. A reasonable value is between 10 and 20.
+1. In the `testaro` directory, make Testaro start listening for jobs: `node call netWatch true nn true`, where `nn` is the number of seconds to wait between checks for new jobs. Note that Kilotest promises nearly immediate review and, on approval, immediate execution of “orders” for tests and retests, with typical total elapsed time 2 to 4 minutes. That promise implies a promise to keep `nn` small. A reasonable value is between 10 and 20.
 1. In the `kilotest` directory, start the Kilotest service: `node index`.
 
 ### Contributing

package/api/orderNewTest.ts

@@ -93,7 +93,7 @@ export const response = async (args: string[]) => {
         'what happens next': 'Testing has begun. Once it finishes, the report will be available via the listIssues tool.',
         'report identifier': {timeStamp, jobID: reportJobID},
         'how you can check for completion': `Call the listIssues tool with timeStamp "${timeStamp}" and jobID "${reportJobID}" to learn whether the report is ready.`,
-        'do you want to wait for completion': 'Testing typically takes about 2 minutes and occasionally up to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same timeStamp and jobID.'
+        'do you want to wait for completion': 'Testing typically takes 2 to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same timeStamp and jobID.'
       };
     }
     else {

package/api/orderRetest.ts

@@ -68,7 +68,7 @@ export const response = async (args: string[]) => {
           'what happens next': 'Testing has begun. Once it finishes, the report will be available via the listIssues tool.',
           'report identifier': {timeStamp: reportTimeStamp, jobID: reportJobID},
           'how you can check for completion': `Call the listIssues tool with timeStamp "${reportTimeStamp}" and jobID "${reportJobID}" to learn whether the report is ready.`,
-          'do you want to wait for completion': 'Testing typically takes about 2 minutes and occasionally up to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same timeStamp and jobID.'
+          'do you want to wait for completion': 'Testing typically takes 2 to 4 minutes. Do you want to wait (and be notified of completion) instead of checking back later? If so, call the awaitTest tool with the same timeStamp and jobID.'
         };
       }
       else {

package/api/util.ts

@@ -51,7 +51,7 @@ export const getResponseMetadata = () => ({
 export const getToolsFacts = () => ({
   'name': 'Kilotest',
   'description': {
-    'what Kilotest does': 'Kilotest tools generate and make available findings about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. A Kilotest job generates findings by using Testaro to test a page against about 1300 rules defined by an ensemble of twelve rule engines. Testaro produces a report of the job. The report describes violations of the rules. Kilotest uses Testilo to enhance the report with a classification of the rule violations into about 380 issues. Kilotest makes facts about the tested pages, the issues, and the violations retrievable at four levels of granularity.',
+    'what Kilotest does': 'Kilotest tools generate and make available findings about the front-end quality (i.e. accessibility, usability, and web standards) of web pages. A Kilotest job generates findings by using Testaro to test a page against about 1300 rules defined by an ensemble of twelve rule engines. Testaro produces a report of the job. The report describes violations of the rules. Kilotest uses Testilo to enhance the report with a classification of the rule violations into about 380 issues. Kilotest makes facts about the tested pages, the issues, and the violations retrievable at four levels of granularity.',
     'how to retrieve findings': {
       'level 1': 'Use the listPages tool to get a list of tested pages, each with its latest report. The listIssues output about any report lists all reports about the same page.',
       'level 2': 'Use the listIssues tool to get a list of issues in one report.',

package/capability.md

@@ -2,7 +2,7 @@
 
 ## Capability
 
-Web-page front-end quality audit. Kilotest tests web pages for front-end quality, namely accessibility, usability, and standards conformity, and makes structured findings available for retrieval.
+Web-page front-end quality audit. Kilotest tests web pages for front-end quality, namely accessibility, usability, and web standards, and makes structured findings available for retrieval.
 
 ## Purpose
 

package/docs/AI-TOOLS.md

@@ -4,7 +4,7 @@
 
 Until 2026 Kilotest was intended, and implemented, as a web application performing a service for human users.
 
-Beginning in May 2026, it [became evident](https://github.com/jrpool/kilotest/issues/2) that Kilotest could operate as a set of tools for language models to allow them to improve their answers to questions about the front-end quality (accessibility, usability, and standards conformity) of specific web pages.
+Beginning in May 2026, it [became evident](https://github.com/jrpool/kilotest/issues/2) that Kilotest could operate as a set of tools for language models to allow them to improve their answers to questions about the front-end quality (accessibility, usability, and web standards) of specific web pages.
 
 A decision was made to **make Kilotest discoverable, usable, and, where appropriate, used as a provider of tools for language models**.
 

package/env.example

@@ -54,7 +54,7 @@ JOB_QUEUE_MAX=__placeholder__
 
 # Timing for the awaitTest MCP tool's wait on a job ordered via orderNewTest/orderRetest.
 # Defaults: 2000ms poll interval, 300000ms (5 minutes) maximum wait. The maximum wait
-# deliberately exceeds the "occasionally up to 4 minutes" callers are told to expect, to
+# deliberately exceeds the "2 to 4 minutes" callers are told to expect, to
 # leave margin so a job that is genuinely still running is not mistaken for one that
 # never will finish. Lower values are useful for local testing.
 

package/index.ts

@@ -31,7 +31,8 @@ import {
   jobsPath,
   metricsExclusionCookieName,
   recordMetric,
-  reportsPath
+  reportsPath,
+  unusableReportsPath
 } from './util.ts';
 import {sendAlert} from './alerts.ts';
 import {checkBalancesForAlerts} from './balances.ts';
@@ -1387,7 +1388,9 @@ export {requestHandler};
 
 const serve = async (protocolModule: typeof http | typeof https, options: {key?: string; cert?: string}) => {
   // Create any missing directories.
-  for (const path of [queuePath(), claimedPath(), failedPath(), hiddenReportsPath(), reportsPath()]) {
+  for (const path of [
+    queuePath(), claimedPath(), failedPath(), hiddenReportsPath(), reportsPath(), unusableReportsPath()
+  ]) {
     await fs.mkdir(path, {recursive: true});
   }
   const server = protocolModule === https

package/lhm.plugin.json

@@ -1,7 +1,7 @@
 {
   "author": "Jonathan Robert Pool",
   "cloudEndpoint": "https://kilotest.com/mcp",
-  "description": "Tools that test web pages for front-end quality (accessibility, usability, and standards conformity) and make test results available",
+  "description": "Tools that test web pages for front-end quality (accessibility, usability, and web standards) and make test results available",
   "homepage": "https://github.com/jrpool/kilotest",
   "identifier": "jrpool-kilotest",
   "name": "Kilotest",
@@ -18,14 +18,14 @@
   "tools": [
     {
       "name": "getKilotestOverview",
-      "description": "Explain what Kilotest is, what its tools do, and how its results are structured. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Explains what Kilotest is, what its tools do, and how its results are structured. Use this before any other tool when the available tools or workflow are unclear. Returns a prose overview of the Kilotest domain, the tool workflow, and links to further documentation. Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and web standards). Each test session generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages.",
       "inputSchema": {
         "type": "object",
         "properties": {},
         "$schema": "http://json-schema.org/draft-07/schema#"
       },
       "annotations": {
-        "title": "Explain what Kilotest is, what its tools do, and how its results are structured. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Explain Kilotest and its tools",
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true,
@@ -37,7 +37,7 @@
     },
     {
       "name": "listPages",
-      "description": "Provide basics about all tested pages, including how to get details about the latest report about each. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Lists all pages Kilotest has tested. Use this first to discover whether a page already has a report before requesting a test. Returns, for each tested page, its description, URL, and the timestamp and job identifier of its latest report.",
       "inputSchema": {
         "type": "object",
         "properties": {},
@@ -400,7 +400,7 @@
         }
       },
       "annotations": {
-        "title": "Provide basics about all tested pages, including how to get details about the latest report about each. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "List tested pages",
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true,
@@ -412,7 +412,7 @@
     },
     {
       "name": "listIssues",
-      "description": "Provide details about one report, including basics about the issues reported in it and the history of all reports about the same page. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Lists the issues reported in one report, along with the history of all reports about the same page. Use this after listPages to drill into a specific report, identified by its timestamp and job identifier. Returns basics about the report's issues and a list of every report about the same page, from oldest to latest.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1139,7 +1139,7 @@
         }
       },
       "annotations": {
-        "title": "Provide details about one report, including basics about the issues reported in it and the history of all reports about the same page. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "List issues in a report",
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true,
@@ -1151,7 +1151,7 @@
     },
     {
       "name": "listViolators",
-      "description": "Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Lists the elements of a tested page that were reported as exhibiting one issue in one report. Use this after listIssues to drill from an issue down to the elements it affects. Returns basics about each violating element, including its identifier in the page's element catalog.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1645,7 +1645,7 @@
         }
       },
       "annotations": {
-        "title": "Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "List elements exhibiting an issue",
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true,
@@ -1657,7 +1657,7 @@
     },
     {
       "name": "listDiagnoses",
-      "description": "Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Lists the diagnoses that rule engines gave for how one element exhibited one issue in one report. Use this after listViolators to drill from an element down to the rule-engine explanations of why it was flagged. Returns, for each rule engine that reported the issue on that element, its diagnosis.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2169,7 +2169,7 @@
         }
       },
       "annotations": {
-        "title": "Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "List diagnoses of a violation",
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true,
@@ -2181,7 +2181,7 @@
     },
     {
       "name": "getReport",
-      "description": "Get one full report in JSON. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Retrieves one entire report as JSON, with all of its issues, violators, and diagnoses. Use this instead of drilling down through listIssues, listViolators, and listDiagnoses when the full report is needed in one call. Returns the complete report data for the specified timestamp and job identifier.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2432,7 +2432,7 @@
         }
       },
       "annotations": {
-        "title": "Get one full report in JSON. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Get a full report",
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true,
@@ -2444,7 +2444,7 @@
     },
     {
       "name": "requestNewTest",
-      "description": "Process my request to test a page about which no report is available yet. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Submits a request to test a page that has no report yet; queued for manual approval. Use orderNewTest instead for immediate, automatically approved testing. Returns a request confirmation with disposition details.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2791,7 +2791,7 @@
         }
       },
       "annotations": {
-        "title": "Process my request to test a page about which no report is available yet. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Request testing of a new page",
         "readOnlyHint": false,
         "destructiveHint": false,
         "idempotentHint": false,
@@ -2803,7 +2803,7 @@
     },
     {
       "name": "requestRetest",
-      "description": "Process my request to retest a page about which a report is available. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Submits a request to retest a page whose existing report is obsolete; queued for manual approval. Use orderRetest instead for immediate, automatically approved retesting. Returns a request confirmation with disposition details.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -3140,7 +3140,7 @@
         }
       },
       "annotations": {
-        "title": "Process my request to retest a page about which a report is available. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Request a retest",
         "readOnlyHint": false,
         "destructiveHint": false,
         "idempotentHint": false,
@@ -3152,7 +3152,7 @@
     },
     {
       "name": "requestFeature",
-      "description": "Process my request to add or improve a feature. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Submits a request to add a new feature or improve an existing one; queued for manual review. There is no immediate-approval alternative for feature requests. Returns a request confirmation with disposition details.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -3414,7 +3414,7 @@
         }
       },
       "annotations": {
-        "title": "Process my request to add or improve a feature. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Request a feature",
         "readOnlyHint": false,
         "destructiveHint": false,
         "idempotentHint": false,
@@ -3426,7 +3426,7 @@
     },
     {
       "name": "orderNewTest",
-      "description": "Process my order to test a page about which no report is available yet, immediately and automatically approved, instead of waiting for manual approval. Testing typically takes about 2 minutes and occasionally up to 4 minutes. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Orders testing of a page that has no report yet, with automated approval or rejection and immediate enqueueing if approved. Use this instead of requestNewTest when immediate testing is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier (timestamp and job identifier) and a question about whether to wait for completion with the awaitTest tool.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -3798,7 +3798,7 @@
         }
       },
       "annotations": {
-        "title": "Process my order to test a page about which no report is available yet, immediately and automatically approved. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Order immediate testing of a new page",
         "readOnlyHint": false,
         "destructiveHint": false,
         "idempotentHint": false,
@@ -3810,7 +3810,7 @@
     },
     {
       "name": "orderRetest",
-      "description": "Process my order to retest a page immediately and automatically approved, instead of waiting for manual approval. Testing typically takes about 2 minutes and occasionally up to 4 minutes. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Orders a retest of a page whose existing report is considered obsolete, with automated approval or rejection and immediate enqueuing if approved. Use this instead of requestRetest when immediate retesting is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier (timestamp and job identifier) and a question about whether to wait for completion with the awaitTest tool.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -4172,7 +4172,7 @@
         }
       },
       "annotations": {
-        "title": "Process my order to retest a page immediately and automatically approved. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Order an immediate retest",
         "readOnlyHint": false,
         "destructiveHint": false,
         "idempotentHint": false,
@@ -4184,7 +4184,7 @@
     },
     {
       "name": "awaitTest",
-      "description": "Wait for a job ordered via the orderNewTest or orderRetest tool to complete, using the report identifier either tool returned. Blocks until the report is ready, the job fails, or a maximum wait time elapses; sends no interim notices. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+      "description": "Waits for a job ordered via the orderNewTest or orderRetest tool to finish, using the report identifier either tool returned. Use this instead of polling listIssues when an immediate answer is preferred. Blocks until the report is ready, the job fails, or a maximum wait time elapses, sending no interim notices; returns the finished job's status and, if ready, its report identifier.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -4495,7 +4495,7 @@
         }
       },
       "annotations": {
-        "title": "Wait for a job ordered via the orderNewTest or orderRetest tool to complete. Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.",
+        "title": "Wait for an ordered job to finish",
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": false,

package/llms-full.txt

@@ -160,7 +160,7 @@ Kilotest offers these tools:
     - `timeStamp`: initial segment of the report identifier returned by `orderNewTest` or `orderRetest`
     - `jobID`: final segment of the report identifier returned by `orderNewTest` or `orderRetest`
   - source of parameters: response to an `orderNewTest` or `orderRetest` request
-  - caveat: testing typically takes about 2 minutes and occasionally up to 4 minutes; sends no interim notices while waiting
+  - caveat: testing typically takes 2 to 4 minutes; sends no interim notices while waiting
 
 ## After a test, retest, or feature request
 

package/llms.txt

@@ -1,6 +1,6 @@
 # Kilotest
 
-Kilotest helps language models and AI platforms to give thorough, accurate and truthful answers when users ask about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. Kilotest integrates an ensemble of twelve independent rule engines to test a web page. Kilotest creates a structured report of the results and saves the report for future reference. Kilotest API endpoints and MCP tools can provide multipage, single-page, and element-level test results.
+Kilotest helps language models and AI platforms to give thorough, accurate and truthful answers when users ask about the front-end quality (i.e. accessibility, usability, and web standards) of web pages. Kilotest integrates an ensemble of twelve independent rule engines to test a web page. Kilotest creates a structured report of the results and saves the report for future reference. Kilotest API endpoints and MCP tools can provide multipage, single-page, and element-level test results.
 
 ## API
 

package/mcp.test.ts

@@ -62,12 +62,12 @@ test('each tool has a description and a handler function', () => {
   const tools = (server as any)._registeredTools;
   for (const [name, tool] of Object.entries(tools) as [string, any][]) {
     assert.ok(tool.description, `${name} has a description`);
-    assert.ok(
-      tool.description.includes('front-end quality'),
-      `${name} description includes the shared domain context`
-    );
     assert.equal(typeof tool.handler, 'function', `${name} has a handler function`);
   }
+  // Only getKilotestOverview repeats the shared domain context in its own description; the
+  // other tools rely on the server instructions for that context, so their descriptions stay
+  // focused on what each tool does, when to use it, and what it returns.
+  assert.ok(tools.getKilotestOverview.description.includes('front-end quality'));
 });
 
 test('getKilotestOverview handler returns overview text and records a metric', async () => {

package/mcp.ts

@@ -50,16 +50,16 @@ import {
 
 export const mcpPath = '/mcp';
 
-// Shared statement of the Kilotest domain and data hierarchy, repeated in every tool
-// description, in the server instructions, and in the getKilotestOverview tool description,
-// because some MCP clients do not propagate server-level instructions or the server
-// description to their models.
-const sharedContext = 'Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.';
+// Shared statement of the Kilotest domain and data hierarchy, repeated in the server
+// instructions and in the getKilotestOverview tool description (but not in the other tool
+// descriptions, to avoid diluting how models read each tool), because some MCP clients do
+// not propagate server-level instructions or the server description to their models.
+const sharedContext = 'Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and web standards). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages.';
 
 // Detailed overview of the Kilotest domain, data hierarchy, and tool workflow, returned by
 // the getKilotestOverview tool and served as the docs://kilotest/overview resource.
 const kilotestOverview = [
-  'Kilotest tests web pages for front-end quality: accessibility, usability, and standards conformity.',
+  'Kilotest tests web pages for front-end quality: accessibility, usability, and web standards.',
   'Kilotest integrates an ensemble of twelve independent rule engines to test a web page and stores the results as a structured report.',
   'Results are organized as a hierarchy. A tested page has one or more reports, from oldest to latest. A report contains issues. An issue has violators: elements of the tested page reported as exhibiting the issue. A violator has diagnoses: explanations from rule engines of how the element exhibited the issue.',
   'Typical workflow: call the listPages tool to learn whether the page has been tested. If it has, drill down from its latest report with the listIssues, listViolators, and listDiagnoses tools, or retrieve the entire report with the getReport tool. The listIssues output also lists all reports about the same page, so you can examine earlier reports. If the page has not been tested, request a test with the requestNewTest tool. If the latest report is obsolete, request a retest with the requestRetest tool.',
@@ -69,16 +69,12 @@ const kilotestOverview = [
 
 // FUNCTIONS
 
-// Returns a tool description consisting of the tool-specific summary followed by the shared
-// Kilotest domain context.
-const toolDoc = (summary: string): string => `${summary} ${sharedContext}`;
-
 // Creates and returns an McpServer with Kilotest tools registered.
 export const createMCPServer = (): McpServer => {
   const server = new McpServer({
     name: 'Kilotest',
     version,
-    description: 'Tools that test web pages for front-end quality (accessibility, usability, and standards conformity) and make test results available'
+    description: 'Tools that test web pages for front-end quality (accessibility, usability, and web standards) and make test results available'
   },
   {
     instructions: `${sharedContext} Use the listPages tool to start. If it shows that the page you want facts about has been tested, drill down from its latest report with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestNewTest tool to request that the page be tested, or the orderNewTest tool for immediate, automatically approved testing. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested, or the orderRetest tool for immediate, automatically approved retesting. For detailed documentation, call the getKilotestOverview tool.`
@@ -86,10 +82,10 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'getKilotestOverview',
     {
-      description: toolDoc('Explain what Kilotest is, what its tools do, and how its results are structured.'),
+      description: `Explains what Kilotest is, what its tools do, and how its results are structured. Use this before any other tool when the available tools or workflow are unclear. Returns a prose overview of the Kilotest domain, the tool workflow, and links to further documentation. ${sharedContext}`,
       inputSchema: {},
       annotations: {
-        title: toolDoc('Explain what Kilotest is, what its tools do, and how its results are structured.'),
+        title: 'Explain Kilotest and its tools',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -104,11 +100,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'listPages',
     {
-      description: toolDoc('Provide basics about all tested pages, including how to get details about the latest report about each.'),
+      description: 'Lists all pages Kilotest has tested. Use this first to discover whether a page already has any reports before requesting a test. Returns, for each tested page, its description, URL, and the timestamp and job identifier of its latest available report.',
       inputSchema: {},
       outputSchema: listPagesResponseSchema,
       annotations: {
-        title: toolDoc('Provide basics about all tested pages, including how to get details about the latest report about each.'),
+        title: 'List tested pages',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -124,11 +120,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'listIssues',
     {
-      description: toolDoc('Provide details about one report, including basics about the issues reported in it and the history of all reports about the same page.'),
+      description: 'Lists the issues reported in one report, along with the history of all reports about the same page. Use this after listPages to switch to an earlier or later report or to begin examining this report. Returns the history and the basics about this report’s issues.',
       inputSchema: listIssuesSchema,
       outputSchema: listIssuesResponseSchema,
       annotations: {
-        title: toolDoc('Provide details about one report, including basics about the issues reported in it and the history of all reports about the same page.'),
+        title: 'List issues in a report',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -144,11 +140,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'listViolators',
     {
-      description: toolDoc('Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue.'),
+      description: 'Lists the elements of a tested page that were reported as exhibiting one issue in one report. Use this after listIssues to drill down from an issue to the elements violating rules belonging to that issue. Returns basics about each violating element.',
       inputSchema: listViolatorsSchema,
       outputSchema: listViolatorsResponseSchema,
       annotations: {
-        title: toolDoc('Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue.'),
+        title: 'List elements exhibiting an issue',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -164,11 +160,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'listDiagnoses',
     {
-      description: toolDoc('Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue.'),
+      description: 'Lists the diagnoses that rule engines gave for how one element exhibited one issue in one report. Use this after listViolators to get details about the element as a violator of the issue. Returns, for each rule engine that reported a violation by the element of a rule belonging to the issue, the diagnosis given by the rule engine.',
       inputSchema: listDiagnosesSchema,
       outputSchema: listDiagnosesResponseSchema,
       annotations: {
-        title: toolDoc('Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue.'),
+        title: 'List diagnoses of a violation',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -184,11 +180,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'getReport',
     {
-      description: toolDoc('Get one full report in JSON.'),
+      description: 'Retrieves one entire report as JSON, with all of its issues, violators, and diagnoses. Use this instead of drilling down through listIssues, listViolators, and listDiagnoses when the full report is needed in one call. Returns the complete report data for the specified timestamp and job identifier. The size of the report is disclosed by the listIssues tool.',
       inputSchema: getReportSchema,
       outputSchema: getReportResponseSchema,
       annotations: {
-        title: toolDoc('Get one full report in JSON.'),
+        title: 'Get a full report',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -204,11 +200,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'requestNewTest',
     {
-      description: toolDoc('Process my request to test a page about which no report is available yet.'),
+      description: 'Submits a request to test a page that has no report yet; queued for manager approval. Use orderNewTest instead for immediate, automatically approved testing. Returns a request confirmation with disposition details.',
       inputSchema: requestNewTestSchema,
       outputSchema: requestNewTestResponseSchema,
       annotations: {
-        title: toolDoc('Process my request to test a page about which no report is available yet.'),
+        title: 'Request testing of a new page',
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -224,11 +220,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'requestRetest',
     {
-      description: toolDoc('Process my request to retest a page about which a report is available.'),
+      description: 'Submits a request to retest a page whose existing report is considered obsolete; queued for manager approval. Use orderRetest instead for immediate, automatically approved retesting. Returns a request confirmation with disposition details.',
       inputSchema: requestRetestSchema,
       outputSchema: requestRetestResponseSchema,
       annotations: {
-        title: toolDoc('Process my request to retest a page about which a report is available.'),
+        title: 'Request a retest',
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -244,11 +240,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'requestFeature',
     {
-      description: toolDoc('Process my request to add or improve a feature.'),
+      description: 'Submits a request to add a new feature or improve an existing one; queued for manager review. There is no immediate-approval alternative for feature requests. Returns a request confirmation with disposition details.',
       inputSchema: requestFeatureSchema,
       outputSchema: requestFeatureResponseSchema,
       annotations: {
-        title: toolDoc('Process my request to add or improve a feature.'),
+        title: 'Request a feature',
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -264,11 +260,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'orderNewTest',
     {
-      description: toolDoc('Process my order to test a page about which no report is available yet, immediately and automatically approved, instead of waiting for manual approval. Testing typically takes about 2 minutes and occasionally up to 4 minutes.'),
+      description: 'Orders testing of a page that has no report yet, with automated approval or rejection and immediate enqueueing if approved. Use this instead of requestNewTest when immediate testing is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier (timestamp and job identifier) and a question about whether to wait for completion with the awaitTest tool.',
       inputSchema: orderNewTestSchema,
       outputSchema: orderNewTestResponseSchema,
       annotations: {
-        title: toolDoc('Process my order to test a page about which no report is available yet, immediately and automatically approved.'),
+        title: 'Order immediate testing of a new page',
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -284,11 +280,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'orderRetest',
     {
-      description: toolDoc('Process my order to retest a page immediately and automatically approved, instead of waiting for manual approval. Testing typically takes about 2 minutes and occasionally up to 4 minutes.'),
+      description: 'Orders a retest of a page whose existing report is considered obsolete, with automated approval or rejection and immediate enqueuing if approved. Use this instead of requestRetest when immediate retesting is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier (timestamp and job identifier) and a question about whether to wait for completion with the awaitTest tool.',
       inputSchema: orderRetestSchema,
       outputSchema: orderRetestResponseSchema,
       annotations: {
-        title: toolDoc('Process my order to retest a page immediately and automatically approved.'),
+        title: 'Order an immediate retest',
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -304,11 +300,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'awaitTest',
     {
-      description: toolDoc('Wait for a job ordered via the orderNewTest or orderRetest tool to complete, using the report identifier either tool returned. Blocks until the report is ready, the job fails, or a maximum wait time elapses; sends no interim notices.'),
+      description: 'Waits for a job ordered via the orderNewTest or orderRetest tool to finish, using the report identifier either tool returned. Use this instead of polling listIssues when an immediate answer is preferred. Blocks until the report is ready, the job fails, or a maximum wait time elapses, sending no interim notices; returns the finished job’s status and, if ready, its report identifier.',
       inputSchema: awaitTestSchema,
       outputSchema: awaitTestResponseSchema,
       annotations: {
-        title: toolDoc('Wait for a job ordered via the orderNewTest or orderRetest tool to complete.'),
+        title: 'Wait for an ordered job to finish',
         readOnlyHint: true,
         idempotentHint: false,
         destructiveHint: false,

package/openapi.yaml

@@ -1,8 +1,8 @@
 openapi: 3.1.0
 info:
   title: Kilotest API
-  description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 12 rule engines to test web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.'
-  version: 58.2.7
+  description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 12 rule engines to test web pages for front-end quality (accessibility, usability, and web standards). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.'
+  version: 59.1.0
   license:
     name: MIT
     identifier: MIT