# MCP Tool Description Optimizer (`trovevault/mcp-tool-description-optimizer`) Actor Optimizes MCP tool descriptions and input schemas with scores, cross-tool confusion risks, rewrites, and warnings. Export data, run via API, schedule and monitor runs, or integrate with other tools. - **URL**: https://apify.com/trovevault/mcp-tool-description-optimizer.md - **Developed by:** [Trove Vault](https://apify.com/trovevault) (community) - **Categories:** AI, Agents, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.70 / 1,000 tools This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## MCP Tool Description Optimizer MCP Tool Description Optimizer audits and rewrites MCP tool definitions so agents choose the right tool more reliably. Paste a tool list from an MCP server, a single tool definition, or a `tools/list` response. The actor returns deterministic improvements for tool descriptions, input schemas, use-case boundaries, cross-tool confusion, and routing warnings. This actor is built for teams shipping MCP servers, AI agent platforms, internal automation catalogs, and tool-heavy assistants where small wording mistakes cause wrong tool calls. It does not use an LLM, so runs are predictable, inexpensive, and easy to review in CI or release workflows. ### What It Optimizes | Output | Why it matters | | --- | --- | | `optimizedDescription` | Adds purpose, use-when guidance, avoid-when boundaries, side-effect language, and required inputs. | | `optimizedSchema` | Adds missing titles, field descriptions, conservative types, required arrays, and `additionalProperties: false` where safe. | | `selectionRiskScore` | Scores how likely an agent is to choose the wrong tool. | | `confusionRiskScore` | Compares tools in the same input and scores cross-tool overlap. | | `potentiallyConfusedWith` | Lists neighboring tools with similar names, schemas, resources, or side-effect profiles. | | `descriptionScore` | Scores whether the original description is specific enough for tool routing. | | `schemaClarityScore` | Scores whether input arguments are clear enough for agents to fill correctly. | | `issues` and `warnings` | Explains what needs review before publishing the optimized definition. | | `optimizedToolDefinition` | Provides a complete revised MCP tool object ready for human review. | | `OPTIMIZED_TOOLS` | Key-value-store manifest containing the full optimized tool list and review summary. | ### Common Use Cases - Review a new MCP server before exposing it to agents. - Improve tool descriptions after seeing wrong tool calls in traces. - Harden destructive tools with clearer confirmation and identifier language. - Add missing schema field descriptions before publishing a tool catalog. - Detect tool pairs that are likely to be confused by agents. - Export a complete optimized manifest for review or downstream CI. - Run deterministic checks in a deployment workflow whenever tool definitions change. ### Input Paste MCP tool JSON into `toolsJson`. The actor accepts a single tool object, an array of tool objects, or an object with a `tools` array. ```json { "tools": [ { "name": "search_documents", "description": "Search docs", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "query" }, "limit": { "type": "integer" } }, "required": ["query"] } }, { "name": "find_document", "description": "Find a document", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "integer" } }, "required": ["query"] } }, { "name": "delete_document", "description": "Delete a document by id", "inputSchema": { "type": "object", "properties": { "documentId": { "type": "string" }, "confirm": { "type": "boolean", "description": "confirm deletion" } }, "required": ["documentId", "confirm"] } } ] } ```` #### Input Fields | Field | Required | Description | | --- | --- | --- | | `toolsJson` | Yes | MCP tool definition JSON to audit and optimize. | | `agentContext` | No | Workflow context, such as "knowledge-base agent with search and delete tools." | | `optimizationGoal` | No | Choose tool-selection accuracy, fewer wrong calls, schema clarity, or compact descriptions. | | `datasetId` | No | Existing Apify dataset ID to append results to as well as the default run dataset. | | `runId` | No | Pipeline metadata copied into each output row. | ### Output Example ```json { "toolName": "search_documents", "riskLevel": "High", "selectionRiskScore": 67, "confusionRiskScore": 59, "descriptionScore": 55, "schemaClarityScore": 78, "optimizedDescription": "Use search_documents to search documents. This tool reads data and should not be used for state-changing requests. Required inputs: query...", "potentiallyConfusedWith": [ { "toolName": "find_document", "similarityScore": 47, "pairRisk": 59, "reasons": ["similar names, descriptions, or schema fields"] } ], "issues": [ "Description is too short to guide tool selection reliably.", "Description does not include avoid-when boundaries.", "Field limit needs a clearer description." ], "optimizedToolDefinition": { "name": "search_documents", "description": "Use search_documents to search documents...", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "Required search text or keywords used to find matching records.", "title": "Query" }, "limit": { "type": "integer", "description": "Optional maximum number of results to return. Use a smaller value for quick agent turns and a larger value for broad retrieval.", "title": "Limit", "minimum": 1, "maximum": 100 } }, "required": ["query"], "additionalProperties": false } } } ``` The run also writes two key-value-store records: - `OPTIMIZED_TOOLS`: full optimized manifest with `optimizedTools`, `confusedPairs`, and `reviewNotes`. - `SUMMARY`: compact counts, average risk score, high-risk tools, and confused pair count. ### How It Works MCP Tool Description Optimizer uses deterministic rules, not generative AI. It analyzes the tool name, original description, input schema fields, required arguments, action verbs, destructive actions, generic wording, missing descriptions, and ambiguous identifiers. It then compares all tools in the same input to find overlapping names, target resources, required arguments, and side-effect profiles. This catches cases where two tools are individually understandable but still risky when exposed together. ### API Usage Run the actor from the Apify API with a bearer token: ```bash curl -X POST "https://api.apify.com/v2/acts/trovevault~mcp-tool-description-optimizer/runs" \ -H "Authorization: Bearer YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "toolsJson": "{\"tools\":[{\"name\":\"search_documents\",\"description\":\"Search docs\",\"inputSchema\":{\"type\":\"object\",\"properties\":{\"query\":{\"type\":\"string\"}},\"required\":[\"query\"]}}]}", "optimizationGoal": "tool_selection_accuracy" }' ``` ### Limits And Review Notes The actor improves observable tool metadata. It cannot prove that a specific agent will always choose correctly, and it cannot infer hidden implementation behavior that is not present in the name, description, or schema. Treat the optimized definitions as review-ready drafts, especially for tools that send messages, mutate records, delete data, or expose sensitive systems. For best results, include all related tools from the same MCP server so similar names and actions can be reviewed together in one dataset. ### Pricing And Performance This actor does not open browsers, crawl websites, or call external AI APIs. It is designed for low-cost runs over tool catalogs and release checks. Runtime mainly depends on the number and size of tool definitions in `toolsJson`. # Actor input Schema ## `toolsJson` (type: `string`): Paste one MCP tool definition, an array of tool definitions, or an MCP tools/list response. The actor accepts common shapes such as {"tools":\[...]}, \[{"name":"..."}], or a single {"name":"..."} object. ## `agentContext` (type: `string`): Describe the agent workflow, tool catalog, or common misrouting problem. This helps the optimizer add more specific use-case and avoid-when language without changing tool behavior. ## `optimizationGoal` (type: `string`): Choose the main quality target. Tool selection accuracy gives the broadest rewrite. Compact descriptions keeps the output shorter for latency-sensitive agents. ## `datasetId` (type: `string`): ID of an existing Apify dataset to append results to, in addition to the default run dataset. Leave blank to use only the default run dataset. ## `runId` (type: `string`): Pipeline or upstream run ID to copy into each output row for downstream joins. ## Actor input object example ```json { "toolsJson": "{\n \"tools\": [\n {\n \"name\": \"search_documents\",\n \"description\": \"Search docs\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": { \"type\": \"string\", \"description\": \"query\" },\n \"limit\": { \"type\": \"integer\" }\n },\n \"required\": [\"query\"]\n }\n },\n {\n \"name\": \"find_document\",\n \"description\": \"Find a document\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": { \"type\": \"string\" },\n \"limit\": { \"type\": \"integer\" }\n },\n \"required\": [\"query\"]\n }\n },\n {\n \"name\": \"delete_document\",\n \"description\": \"Delete a document by id\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"documentId\": { \"type\": \"string\" },\n \"confirm\": { \"type\": \"boolean\", \"description\": \"confirm deletion\" }\n },\n \"required\": [\"documentId\", \"confirm\"]\n }\n }\n ]\n}", "agentContext": "Knowledge-base agent with document search, retrieval, update, and deletion tools.", "optimizationGoal": "tool_selection_accuracy" } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `optimizedToolsManifest` (type: `string`): No description ## `summary` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "toolsJson": `{ "tools": [ { "name": "search_documents", "description": "Search docs", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "query" }, "limit": { "type": "integer" } }, "required": ["query"] } }, { "name": "find_document", "description": "Find a document", "inputSchema": { "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "integer" } }, "required": ["query"] } }, { "name": "delete_document", "description": "Delete a document by id", "inputSchema": { "type": "object", "properties": { "documentId": { "type": "string" }, "confirm": { "type": "boolean", "description": "confirm deletion" } }, "required": ["documentId", "confirm"] } } ] }`, "agentContext": "Knowledge-base agent with document search, retrieval, update, and deletion tools." }; // Run the Actor and wait for it to finish const run = await client.actor("trovevault/mcp-tool-description-optimizer").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "toolsJson": """{ \"tools\": [ { \"name\": \"search_documents\", \"description\": \"Search docs\", \"inputSchema\": { \"type\": \"object\", \"properties\": { \"query\": { \"type\": \"string\", \"description\": \"query\" }, \"limit\": { \"type\": \"integer\" } }, \"required\": [\"query\"] } }, { \"name\": \"find_document\", \"description\": \"Find a document\", \"inputSchema\": { \"type\": \"object\", \"properties\": { \"query\": { \"type\": \"string\" }, \"limit\": { \"type\": \"integer\" } }, \"required\": [\"query\"] } }, { \"name\": \"delete_document\", \"description\": \"Delete a document by id\", \"inputSchema\": { \"type\": \"object\", \"properties\": { \"documentId\": { \"type\": \"string\" }, \"confirm\": { \"type\": \"boolean\", \"description\": \"confirm deletion\" } }, \"required\": [\"documentId\", \"confirm\"] } } ] }""", "agentContext": "Knowledge-base agent with document search, retrieval, update, and deletion tools.", } # Run the Actor and wait for it to finish run = client.actor("trovevault/mcp-tool-description-optimizer").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "toolsJson": "{\\n \\"tools\\": [\\n {\\n \\"name\\": \\"search_documents\\",\\n \\"description\\": \\"Search docs\\",\\n \\"inputSchema\\": {\\n \\"type\\": \\"object\\",\\n \\"properties\\": {\\n \\"query\\": { \\"type\\": \\"string\\", \\"description\\": \\"query\\" },\\n \\"limit\\": { \\"type\\": \\"integer\\" }\\n },\\n \\"required\\": [\\"query\\"]\\n }\\n },\\n {\\n \\"name\\": \\"find_document\\",\\n \\"description\\": \\"Find a document\\",\\n \\"inputSchema\\": {\\n \\"type\\": \\"object\\",\\n \\"properties\\": {\\n \\"query\\": { \\"type\\": \\"string\\" },\\n \\"limit\\": { \\"type\\": \\"integer\\" }\\n },\\n \\"required\\": [\\"query\\"]\\n }\\n },\\n {\\n \\"name\\": \\"delete_document\\",\\n \\"description\\": \\"Delete a document by id\\",\\n \\"inputSchema\\": {\\n \\"type\\": \\"object\\",\\n \\"properties\\": {\\n \\"documentId\\": { \\"type\\": \\"string\\" },\\n \\"confirm\\": { \\"type\\": \\"boolean\\", \\"description\\": \\"confirm deletion\\" }\\n },\\n \\"required\\": [\\"documentId\\", \\"confirm\\"]\\n }\\n }\\n ]\\n}", "agentContext": "Knowledge-base agent with document search, retrieval, update, and deletion tools." }' | apify call trovevault/mcp-tool-description-optimizer --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=trovevault/mcp-tool-description-optimizer", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "MCP Tool Description Optimizer", "description": "Optimizes MCP tool descriptions and input schemas with scores, cross-tool confusion risks, rewrites, and warnings. Export data, run via API, schedule and monitor runs, or integrate with other tools.", "version": "0.1", "x-build-id": "7wtpVHT6WzVUY0PNf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/trovevault~mcp-tool-description-optimizer/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-trovevault-mcp-tool-description-optimizer", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/trovevault~mcp-tool-description-optimizer/runs": { "post": { "operationId": "runs-sync-trovevault-mcp-tool-description-optimizer", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/trovevault~mcp-tool-description-optimizer/run-sync": { "post": { "operationId": "run-sync-trovevault-mcp-tool-description-optimizer", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "toolsJson" ], "properties": { "toolsJson": { "title": "MCP Tools JSON", "type": "string", "description": "Paste one MCP tool definition, an array of tool definitions, or an MCP tools/list response. The actor accepts common shapes such as {\"tools\":[...]}, [{\"name\":\"...\"}], or a single {\"name\":\"...\"} object." }, "agentContext": { "title": "Agent Context (optional)", "type": "string", "description": "Describe the agent workflow, tool catalog, or common misrouting problem. This helps the optimizer add more specific use-case and avoid-when language without changing tool behavior." }, "optimizationGoal": { "title": "Optimization Goal", "enum": [ "tool_selection_accuracy", "reduce_wrong_tool_calls", "schema_clarity", "compact_descriptions" ], "type": "string", "description": "Choose the main quality target. Tool selection accuracy gives the broadest rewrite. Compact descriptions keeps the output shorter for latency-sensitive agents.", "default": "tool_selection_accuracy" }, "datasetId": { "title": "Dataset ID (optional)", "type": "string", "description": "ID of an existing Apify dataset to append results to, in addition to the default run dataset. Leave blank to use only the default run dataset." }, "runId": { "title": "Run ID (optional)", "type": "string", "description": "Pipeline or upstream run ID to copy into each output row for downstream joins." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```