# MCP Tool Description Optimizer (`trovevault/mcp-tool-description-optimizer`) Actor Optimizes MCP tool descriptions and input schemas with scores, 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:** 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — 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, a single tool definition, a `tools/list` response, or an upstream run ID. The actor returns deterministic improvements for descriptions, schemas, use-case boundaries, cross-tool confusion, and routing warnings. It is built for teams shipping MCP servers, agent platforms, automation catalogs, and tool-heavy assistants where small wording mistakes cause wrong tool calls. It uses deterministic rules, so runs are predictable and easy to review in CI. ### What does MCP Tool Description Optimizer do? | Output | Why it matters | | --- | --- | | `optimizedDescription` | Adds purpose, use-when guidance, avoid-when boundaries, side-effect language, and required inputs. | | `optimizedSchema` | Adds 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. | ### Why use MCP Tool Description Optimizer? - Review a new MCP server before agents use it. - 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 checks in deployment workflows whenever tool definitions change. ### How do I run MCP Tool Description Optimizer? 1. Paste MCP tool JSON into `toolsJson`, or pass `runId` from an upstream Apify run with tool rows. 2. Pick `optimizationGoal`: broad accuracy, fewer wrong calls, schema clarity, or compact descriptions. 3. Run the actor and review `optimizedDescription`, `optimizedSchema`, `issues`, and `warnings`. 4. Copy reviewed definitions from the dataset or `OPTIMIZED_TOOLS`. ### What input does MCP Tool Description Optimizer accept? Paste MCP tool JSON into `toolsJson`, or pass `runId` to reprocess tool rows from a previous Apify run dataset. Accepted shapes are a single tool object, an array, or an object with a `tools` array. ```json { "tools": [ { "name": "search_documents", "description": "Search docs", "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" } }, "required": ["documentId", "confirm"] } } ] } ``` #### Input Fields | Field | Required | Description | | --- | --- | --- | | `toolsJson` | No | MCP tool JSON to audit. Required unless `runId` points to an upstream dataset with tool rows. | | `agentContext` | No | Agent workflow or misrouting pattern, such as "knowledge-base agent with search and delete tools." | | `optimizationGoal` | No | Tool selection accuracy, fewer wrong calls, schema clarity, or compact descriptions. Default: `tool_selection_accuracy`. | | `datasetId` | No | Existing Apify dataset ID for appending output rows in addition to the default run dataset. | | `runId` | No | Upstream run ID. If `toolsJson` is blank, the actor reads tool rows from that run's dataset; otherwise it copies this value into each row. | ### What data does MCP Tool Description Optimizer return? ```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", "pairRisk": 59 }], "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", "title": "Limit", "minimum": 1, "maximum": 100 } }, "required": ["query"], "additionalProperties": false } } } ``` The run also writes two key-value-store records: - `OPTIMIZED_TOOLS`: optimized manifest with `optimizedTools`, `confusedPairs`, and `reviewNotes`. - `SUMMARY`: counts, average risk score, high-risk tools, and confused pair count. ### How does MCP Tool Description Optimizer work? MCP Tool Description Optimizer uses deterministic rules, not generative AI. It analyzes tool names, descriptions, 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. ### How can I run MCP Tool Description Optimizer by API? 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 $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" }' ``` ### How can I integrate MCP Tool Description Optimizer? Use `datasetId` to append every run to the same review dataset. Use `runId` when a previous step already produced MCP tool rows. ```js const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); await client.actor('trovevault/mcp-tool-description-optimizer').call({ runId: 'UPSTREAM_RUN_ID', datasetId: 'REVIEW_DATASET_ID', optimizationGoal: 'reduce_wrong_tool_calls' }); ``` ### How much does MCP Tool Description Optimizer cost? The actor uses pay-per-event pricing: Actor Start plus one primary Tool event per dataset item, with tier discounts shown on the actor page. ### What are the limits and review notes? The actor improves observable tool metadata. It cannot prove that a specific agent will always choose correctly or infer hidden implementation behavior. Treat output 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. ### How do I troubleshoot MCP Tool Description Optimizer? | Problem | What to try | | --- | --- | | Input JSON is rejected | Validate that `toolsJson` is a JSON object, a JSON array, or an object with a `tools` array. | | Results miss cross-tool confusion | Include the full related tool list from the same MCP server, not just one tool. | | Optimized descriptions feel too verbose | Set `optimizationGoal` toward compact descriptions and review `issues` before copying output. | | Destructive tools still look risky | Treat the output as a draft and manually review side effects, confirmation fields, and irreversible actions. | | Need a CI workflow | Store the `OPTIMIZED_TOOLS` key-value-store record and compare it in your own release process. | ### FAQ **Does this actor use an LLM?**\ No. It uses deterministic rules so output is predictable and easier to review. **Can it guarantee that agents choose the right tool?** No. Final routing still depends on the agent, prompt, neighboring tools, and runtime context. **Can it rewrite an entire MCP server manifest?**\ Yes. Provide the tool list as JSON and review the `OPTIMIZED_TOOLS` manifest. **Should I publish optimized definitions automatically?** No. Review tools that delete, send, purchase, mutate records, or expose sensitive systems. **Why include all related tools?**\ Cross-tool confusion is only visible when the actor can compare neighboring tools in the same catalog. **Can I use it for non-MCP tool schemas?**\ It works best on MCP-style tool definitions, but similar JSON tool lists can still produce useful clarity and risk notes. **Can it infer hidden behavior from code?**\ No. It only reviews the metadata you provide. ### Feedback and support Open an issue on the actor page with the input JSON, run ID, tool name, and the specific optimization or warning you expected. # Actor input Schema ## `toolsJson` (type: `string`): Paste MCP tool definitions as JSON. Accepted formats: a single {"name":"..."} tool, an array like \[{"name":"search\_documents"}], or a tools/list response such as {"tools":\[...]}. Leave blank only when runId points to a previous run dataset containing tool rows. ## `agentContext` (type: `string`): Describe the agent workflow, tool catalog, or repeated wrong-tool-call pattern. Examples: "support agent with search and ticket update tools" or "knowledge-base agent with search and delete tools". Leave blank for generic MCP routing guidance. ## `optimizationGoal` (type: `string`): Choose the main optimization target. tool\_selection\_accuracy gives the broadest rewrite, reduce\_wrong\_tool\_calls emphasizes use/avoid boundaries, schema\_clarity focuses on argument metadata, and compact\_descriptions keeps output shorter. Default: tool\_selection\_accuracy. ## `datasetId` (type: `string`): Optional Apify dataset ID that receives a copy of every output row in addition to the default run dataset. Use an existing dataset ID such as "abc123" for shared review pipelines. Leave blank to write only to the default dataset. ## `runId` (type: `string`): Optional upstream Apify run ID used for pipeline joins and dataset reuse. If toolsJson is blank, the actor reads MCP tool rows from that run's default dataset; otherwise it copies this ID into each output row. Leave blank for standalone runs. ## 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 Download the OpenAPI definition: https://api.apify.com/v2/actors/lr5l8FxlOzk81mDYS/builds/9FzjC6uzUs0MKXrV8/openapi.json