feat: Update tool descriptions

Author: jirispilka

src/tools/actor.ts

@@ -317,8 +317,7 @@ export const callActor: ToolEntry = {
     tool: {
         name: HelperTools.ACTOR_CALL,
         actorFullName: HelperTools.ACTOR_CALL,
-        description: `Call Any Actor from Apify Store - Two-Step Process
-
+        description: `Call any Actor from Apify Store - two-step process
 This tool uses a mandatory two-step process to safely call any Actor from the Apify store.
 
 USAGE:
@@ -328,13 +327,14 @@ USAGE:
 MANDATORY TWO-STEP WORKFLOW:
 
 Step 1: Get Actor Info (step="info", default)
-• First call this tool with step="info" to get Actor details and input schema
-• This returns the Actor description, documentation, and required input schema
-• You MUST do this step first - it's required to understand how to call the Actor
-
-Step 2: Call Actor (step="call") 
-• Only after step 1, call again with step="call" and proper input based on the schema
-• This executes the Actor and returns the results
+- First call this tool with step="info" to get Actor details and input schema
+- This returns the Actor description, documentation, and required input schema
+- You MUST do this step first - it's required to understand how to call the Actor
+
+Step 2: Call Actor (step="call")
+- Only after step 1, call again with step="call" and proper input based on the schema
+- This calls and runs the Actor. It will create an output as an Apify dataset (with datasetId).
+- This step returns a dataset preview, typically JSON-formatted tabular data.
 
 The step parameter enforces this workflow - you cannot call an Actor without first getting its info.`,
         inputSchema: zodToJsonSchema(callActorArgs),

src/tools/fetch-actor-details.ts

@@ -17,15 +17,16 @@ export const fetchActorDetailsTool: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.ACTOR_GET_DETAILS,
-        description: `Get detailed information about an Actor by its ID or full name.\n`
-            + `This tool returns title, description, URL, README (Actor's documentation), input schema, and usage statistics. \n`
-            + `The Actor name is always composed of "username/name", for example, "apify/rag-web-browser".\n`
-            + `Present Actor information in user-friendly format as an Actor card.\n`
-            + `USAGE:\n`
-            + `- Use when user asks about an Actor its details, description, input schema, etc.\n`
-            + `EXAMPLES:\n`
-            + `- user_input: How to use apify/rag-web-browser\n`
-            + `- user_input: What is the input schema for apify/rag-web-browser`,
+        description: `Get detailed information about an Actor by its ID or full name.
+This tool returns title, description, URL, README (Actor's documentation), input schema, and usage statistics.
+The Actor name is always composed of "username/name", for example, "apify/rag-web-browser".
+Present Actor information in user-friendly format as an Actor card.
+USAGE:
+- Use when user asks about an Actor its details, description, input schema, etc.
+EXAMPLES:
+- user_input: How to use apify/rag-web-browser
+- user_input: What is the input schema for apify/rag-web-browser,
+- user_input: What is pricing of apify/instagram-scraper?`,
         inputSchema: zodToJsonSchema(fetchActorDetailsToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(fetchActorDetailsToolArgsSchema)),
         call: async (toolArgs) => {

src/tools/get-actor-output.ts

@@ -68,10 +68,19 @@ export const getActorOutput: ToolEntry = {
     tool: {
         name: HelperTools.ACTOR_OUTPUT_GET,
         actorFullName: HelperTools.ACTOR_OUTPUT_GET,
-        description: `Retrieves the output of a specific Actor execution based on its dataset ID.
-You can also retrieve only specific fields from the output if needed. Use this tool to get Actor output data outside of the Actor dataset output preview, or to access fields from the Actor output dataset schema that are not included in the preview.
+        description: `Fetch the dataset of a specific Actor run based on datasetId.
+You can also retrieve only specific fields from the output if needed.
 
-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\`).`,
+USAGE:
+- Use this tool to get Actor dataset outside of the preview, or to access fields from the Actor output
+dataset schema that are not included in the preview.
+
+EXAMPLES:
+- user_input: Get data of my last Actor run?
+- user_input: Get number_of_likes from my dataset?
+
+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: zodToJsonSchema(getActorOutputArgs),
         /**
          * Allow additional properties for Skyfire mode to pass `skyfire-pay-id`.

src/tools/search-apify-docs.ts

@@ -30,12 +30,25 @@ export const searchApifyDocsTool: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.DOCS_SEARCH,
-        description: `Apify documentation search tool. This tool allows you to search the Apify documentation using Algolia's full-text search.\n`
-            + 'You can use it to find relevant documentation pages based on keywords. The results will include the URL of the documentation page, '
-            + 'a fragment identifier (if available), and a limited piece of content that matches the search query. '
-            + `You can then fetch the full content of the document using the ${HelperTools.DOCS_FETCH} tool by providing the URL.\n`
-            + 'Use this tool when a user asks for help with Apify documentation or when you need to find relevant documentation pages based on keywords. '
-            + 'For example, when a user wants to build an Apify Actor, you can search "How to build Actors" to find relevant guidance.',
+        description: `Search Apify documentation using full-text search.
+    You can use it to find relevant documentation based on keywords.
+    Apify documentation has information about Apify console, Actors (development
+    (actor.json, input schema, dataset schema, dockerfile), deployment, builds, runs),
+    schedules, storages (datasets, key-value store), Proxy, Integrations,
+    Apify Academy (crawling and webscraping with Crawlee),
+
+    The results will include the URL of the documentation page, a fragment identifier (if available),
+    and a limited piece of content that matches the search query.
+
+    Fetch the full content of the document using the ${HelperTools.DOCS_FETCH} tool by providing the URL.
+
+    USAGE:
+    - Use when user asks about Apify documentation, Actor development, Crawlee, or Apify platform.
+
+    EXAMPLES:
+    - query: How to use create Apify Actor?
+    - query: How to define Actor input schema?
+    - query: How scrape with Crawlee?`,
         args: searchApifyDocsToolArgsSchema,
         inputSchema: zodToJsonSchema(searchApifyDocsToolArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(searchApifyDocsToolArgsSchema)),
@@ -59,7 +72,7 @@ export const searchApifyDocsTool: ToolEntry = {
 
             const textContent = `You can use the Apify docs fetch tool to retrieve the full content of a document by its URL. The document fragment refers to the section of the content containing the relevant part for the search result item.
 Search results for "${query}":
-                    
+
 ${results.map((result) => `- Document URL: ${result.url}${result.fragment ? `\n  Document fragment: ${result.fragment}` : ''}
   Content: ${result.content}`).join('\n\n')}`;
             return {

src/tools/store_collection.ts

@@ -71,21 +71,27 @@ export const searchActors: ToolEntry = {
     type: 'internal',
     tool: {
         name: HelperTools.STORE_SEARCH,
-        description: `Search for Actors or Model Context Protocol (MCP) servers in the Apify Store using keywords.\n`
-            + `This tool returns a list of Actors with title, description, pricing model, usage statistics, and user ratings.\n`
-            + `Use simple space-separated keywords for best results, such as "web scraping", "data extraction", or "playwright mcp".\n`
-            + `You may need to use this tool several times to find the right Actor.\n`
-            + `Limit the number of results returned, but ensure that relevant results are included.\n`
-            + `Always present the results in a user-friendly format as an Actor cards.\n\n`
-            + `USAGE:\n`
-            + `- Use when user wants to find Actors for a specific task or technology\n`
-            + `- Use when user asks about available Actors in the Apify Store\n`
-            + `- Use when user needs to discover MCP servers or automation tools\n`
-            + `EXAMPLES:\n`
-            + `- user_input: Find Actors for web scraping\n`
-            + `- user_input: Search for MCP servers\n`
-            + `- user_input: What Actors are available for data extraction\n`
-            + `- user_input: Show me Actors that use Playwright`,
+        description: `Search the Apify Store for Actors or Model Context Protocol (MCP) servers using keywords.
+Apify is the largest platform for web scrapers, AI agents, and automation tools, called Actors.
+The store features solutions for scraping Instagram, Twitter, TikTok, LinkedIn, Bookings, Flights and more.
+All Actors are verified and comply with scraping guidelines.
+
+This tool returns a curated list of Actors, including their title, description, pricing model, usage statistics, and user ratings.
+For best results, use simple space-separated keywords (e.g., "instagram posts", "twitter profile", "playwright mcp").
+You may need to run multiple searches to find the most suitable Actor.
+Limit the number of results to keep responses relevant and concise.
+Results are always presented as user-friendly Actor cards.
+
+USAGE:
+- Use when a user wants to find Actors for a specific task
+- Use when a user asks about specific data and available Actors in the Apify Store
+- Use when a user needs to discover MCP servers or automation tools
+
+EXAMPLES:
+- user_input: Find Actors for scraping e-commerce
+- user_input: Find browserbase MCP server
+- user_input: I need to scrape instagram profiles/comments
+- user_input: I need to get flights and airbnb data`,
         inputSchema: zodToJsonSchema(searchActorsArgsSchema),
         ajvValidate: ajv.compile(zodToJsonSchema(searchActorsArgsSchema)),
         call: async (toolArgs) => {