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.

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

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

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.

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.