feat: Adopt dedent for multiline tool descriptions (#609)

* feat: adopt dedent for multiline tool descriptions in pilot files

Add `dedent` dependency and convert 3 pilot files to use `dedent` tagged
template literals for long description strings:
- src/tools/common/get_dataset_items.ts
- src/tools/common/dataset_collection.ts
- src/tools/common/get_actor_output.ts

Add string formatting rules to CONTRIBUTING.md documenting the convention.

Resolves #574

https://claude.ai/code/session_01PQP1ovrVPikt86BGPDecUt

* feat: dedent formatting in Actor response

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: jirispilka

CONTRIBUTING.md

@@ -78,6 +78,40 @@ Use comments to guide reviewers:
     * **Zod Validators:** Suffix with `Validator`.
     * **Text/Copy:** Use the branded term `Actor` (capitalized) instead of `actor` in user-facing texts, labels, notifications, error messages, etc.
 
+*   **String formatting:**
+    * Use plain single-quoted strings for short one-liners.
+    * Use `dedent` (tagged template literal) for any string that would otherwise exceed `max-len` or span multiple lines — including tool `description` fields, LLM instructions, and single-sentence strings that are simply long.
+        * Inline `dedent` directly as a property or variable value — do not extract it to a named constant.
+        * `dedent` introduces `\n` at each source line break. This is fine for LLM-facing strings (tool descriptions, instructions, notes), but avoid it for strings where whitespace is significant or where `\n` would break rendering (e.g. UI labels, log messages, URLs).
+        * For strings where `\n` is not acceptable, use string concatenation (`+`) to split across lines for `max-len` compliance.
+        ```typescript
+        import dedent from 'dedent';
+
+        // Multi-line prose — always use dedent
+        export const toolEntry = {
+            name: 'example-tool',
+            description: dedent`
+                Line 1.
+                Line 2.
+
+                USAGE:
+                - Example
+            `,
+        };
+
+        // Long single sentence going to LLM — dedent is fine, \n is ok
+        const note = isLimited ? dedent`
+            You only have a preview (${count} of ${total} items).
+            Do not present this as the full output.
+        ` : '';
+
+        // Long string where \n is NOT ok (e.g. log message) — use + instead
+        const msg = `Something failed for actor "${actorName}"`
+            + ` with status ${status}.`;
+        ```
+    * Avoid `[].join('\n')` for multiline strings — it is noisy and harder to edit.
+    * When migrating existing strings, keep the wording **semantically unchanged**.
+
 *   **Comments:**
     * Use proper English (spelling, grammar, punctuation, capitalization).
     * Use JSDoc `/**` for documentation, `//` for generic comments, and avoid `/*` (single asterix multiline comments).

package-lock.json

@@ -51,6 +51,7 @@
     "algoliasearch": "^5.31.0",
     "apify": "^3.4.2",
     "apify-client": "^2.22.1",
+    "dedent": "^1.7.2",
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
     "mcp-client-capabilities": "^0.0.5",

package.json

@@ -1,3 +1,4 @@
+import dedent from 'dedent';
 import { z } from 'zod';
 
 import { ApifyClient } from '../../apify_client.js';
@@ -27,18 +28,19 @@ const getUserDatasetsListArgs = z.object({
 export const getUserDatasetsList: ToolEntry = Object.freeze({
     type: 'internal',
     name: HelperTools.DATASET_LIST_GET,
-    description: `List datasets (collections of Actor run data) for the authenticated user.
-Actor runs automatically produce unnamed datasets (set unnamed=true to include them). Users can also create named datasets.
+    description: dedent`
+        List datasets (collections of Actor run data) for the authenticated user.
+        Actor runs automatically produce unnamed datasets (set unnamed=true to include them). Users can also create named datasets.
 
-The results will include datasets with itemCount, access settings, and usage stats, sorted by createdAt (ascending by default).
-Use limit (max 20), offset, and desc to paginate and sort.
+        The results will include datasets with itemCount, access settings, and usage stats, sorted by createdAt (ascending by default).
+        Use limit (max 20), offset, and desc to paginate and sort.
 
-USAGE:
-- Use when you need to browse available datasets (named or unnamed) to locate data.
+        USAGE:
+        - Use when you need to browse available datasets (named or unnamed) to locate data.
 
-USAGE EXAMPLES:
-- user_input: List my last 10 datasets (newest first)
-- user_input: List unnamed datasets`,
+        USAGE EXAMPLES:
+        - user_input: List my last 10 datasets (newest first)
+        - user_input: List unnamed datasets`,
     inputSchema: z.toJSONSchema(getUserDatasetsListArgs) as ToolInputSchema,
     ajvValidate: compileSchema(z.toJSONSchema(getUserDatasetsListArgs)),
     annotations: {

src/tools/common/dataset_collection.ts

@@ -1,3 +1,4 @@
+import dedent from 'dedent';
 import { z } from 'zod';
 
 import { createApifyClientWithSkyfireSupport } from '../../apify_client.js';
@@ -67,23 +68,24 @@ export function cleanEmptyProperties(obj: unknown): unknown {
 export const getActorOutput: ToolEntry = Object.freeze({
     type: 'internal',
     name: HelperTools.ACTOR_OUTPUT_GET,
-    description: `Retrieve the output dataset items of a specific Actor run using its datasetId.
-You can select specific fields to return (supports dot notation like "crawl.statusCode") and paginate results with offset and limit.
-This tool is a simplified version of the get-dataset-items tool, focused on Actor run outputs.
+    description: dedent`
+        Retrieve the output dataset items of a specific Actor run using its datasetId.
+        You can select specific fields to return (supports dot notation like "crawl.statusCode") and paginate results with offset and limit.
+        This tool is a simplified version of the get-dataset-items tool, focused on Actor run outputs.
 
-The results will include the dataset items from the specified dataset. If you provide fields, only those fields will be included (nested fields supported via dot notation).
+        The results will include the dataset items from the specified dataset. If you provide fields, only those fields will be included (nested fields supported via dot notation).
 
-You can obtain the datasetId from an Actor run (e.g., after calling an Actor with the call-actor tool) or from the Apify Console (Runs → Run details → Dataset ID).
+        You can obtain the datasetId from an Actor run (e.g., after calling an Actor with the call-actor tool) or from the Apify Console (Runs → Run details → Dataset ID).
 
-USAGE:
-- Use when you need to read Actor output data (full items or selected fields), especially when preview does not include all fields.
+        USAGE:
+        - Use when you need to read Actor output data (full items or selected fields), especially when preview does not include all fields.
 
-USAGE EXAMPLES:
-- user_input: Get data of my last Actor run
-- user_input: Get number_of_likes from my dataset
-- user_input: Return only crawl.statusCode and url from dataset aab123
+        USAGE EXAMPLES:
+        - user_input: Get data of my last Actor run
+        - user_input: Get number_of_likes from my dataset
+        - user_input: Return only crawl.statusCode and url from dataset aab123
 
-Note: This tool is automatically included if the Apify MCP Server is configured with any Actor tools (e.g., "apify-slash-rag-web-browser") or tools that can interact with Actors (e.g., "call-actor", "add-actor").`,
+        Note: This tool is automatically included if the Apify MCP Server is configured with any Actor tools (e.g., "apify-slash-rag-web-browser") or tools that can interact with Actors (e.g., "call-actor", "add-actor").`,
     inputSchema: z.toJSONSchema(getActorOutputArgs) as ToolInputSchema,
     outputSchema: datasetItemsOutputSchema,
     /**

src/tools/common/get_actor_output.ts

@@ -1,3 +1,4 @@
+import dedent from 'dedent';
 import { z } from 'zod';
 
 import { createApifyClientWithSkyfireSupport } from '../../apify_client.js';
@@ -38,18 +39,19 @@ const getDatasetItemsArgs = z.object({
 export const getDatasetItems: ToolEntry = Object.freeze({
     type: 'internal',
     name: HelperTools.DATASET_GET_ITEMS,
-    description: `Retrieve dataset items with pagination, sorting, and field selection.
-Use clean=true to skip empty items and hidden fields. Include or omit fields using comma-separated lists.
-For nested objects, first flatten them (e.g., flatten="metadata"), then reference nested fields via dot notation (e.g., fields="metadata.url").
+    description: dedent`
+        Retrieve dataset items with pagination, sorting, and field selection.
+        Use clean=true to skip empty items and hidden fields. Include or omit fields using comma-separated lists.
+        For nested objects, first flatten them (e.g., flatten="metadata"), then reference nested fields via dot notation (e.g., fields="metadata.url").
 
-The results will include items along with pagination info (limit, offset) and total count.
+        The results will include items along with pagination info (limit, offset) and total count.
 
-USAGE:
-- Use when you need to read data from a dataset (all items or only selected fields).
+        USAGE:
+        - Use when you need to read data from a dataset (all items or only selected fields).
 
-USAGE EXAMPLES:
-- user_input: Get first 100 items from dataset abd123
-- user_input: Get only metadata.url and title from dataset username~my-dataset (flatten metadata)`,
+        USAGE EXAMPLES:
+        - user_input: Get first 100 items from dataset abd123
+        - user_input: Get only metadata.url and title from dataset username~my-dataset (flatten metadata)`,
     inputSchema: z.toJSONSchema(getDatasetItemsArgs) as ToolInputSchema,
     outputSchema: datasetItemsOutputSchema,
     /**