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.

{
  "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

{
  "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:

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.