Write Effective MCP Tool Descriptions

On This Page

This page is for developers. It describes how to write tool descriptions that help external AI applications select and use Model Context Protocol (MCP) tools correctly.

Appian MCP Server enforces the same object security, record-level security, and group membership as the Appian platform. When you make a design object available as an MCP tool on Appian MCP Server, you provide a tool description. AI applications use this description to decide when your tool is the right choice for a user's request. A well-written description directly affects whether the AI application selects your tool, ignores it, or misuses it.

Why descriptions matter

AI applications do not see your Model Context Protocol (MCP) tool's implementation details. They see only the tool name, description, and input schema. The AI application uses the description to:

Decide when to use the tool: The description tells the AI application what scenarios the tool is designed for.
Understand what the tool does: The description communicates the tool's purpose and expected outcome.
Provide correct inputs: The description helps the AI application understand what information to pass to the tool.

A vague or misleading description causes the AI application to select the wrong tool, skip your tool entirely, or pass incorrect inputs.

Structure of a good description

An effective Model Context Protocol (MCP) tool description answers three questions:

What does this tool do? A clear, specific statement of the tool's purpose and output.
When is this tool the right choice? Context about the scenarios where this tool is appropriate.
What inputs does it need? A brief mention of key inputs, especially when the input names alone are not self-explanatory.

Keep descriptions concise—two to four sentences. AI applications process descriptions as part of their reasoning, and overly long descriptions add noise.

Examples of good and bad descriptions

The following examples show how Model Context Protocol (MCP) tool descriptions affect AI application behavior.

AI agent example

Good description:

Analyze a customer complaint and recommend a resolution category. Use this tool when a support case contains unstructured customer feedback that needs classification. Send the complaint text as the message.

Why this works: The description explains the agent's role (complaint analysis and classification), when to invoke it (unstructured feedback needing classification), and how to provide input (complaint text as the message).

Bad description:

Customer support agent.

Why this fails: The AI application cannot determine what this agent does, when to invoke it, or what kind of input to provide.

Expression rule example

Good description:

Calculate the shipping cost for an order based on weight, destination region, and shipping speed. Use this tool when you need to estimate or display shipping costs for a customer order. Requires order weight in kilograms, destination region code, and selected shipping tier.

Why this works: The description specifies the calculation (shipping cost), the use case (estimating costs for orders), and the required inputs with expected formats.

Bad description:

Calculates costs.

Why this fails: The AI application cannot distinguish this tool from any other cost calculation. The description does not explain what kind of cost, when to use it, or what inputs are needed.

Business process example

Good description:

Show me the cases that have Spain as attribute and take longer than the average duration to complete.

Why this works: The description gives a clear description of what should be queried.

Bad description:

Show cases.

Why this fails: Too vague. The AI application cannot determine when to use this tool or what specific details are needed.

Process model example

Good description:

Start the employee onboarding workflow for a new hire. Use this tool when a new employee record has been created and needs to be routed through IT provisioning, facilities setup, and manager introduction. Requires the employee ID and start date.

Why this works: The description states what the tool does (starts onboarding), when to use it (after employee record creation), and what inputs are needed (employee ID and start date).

Bad description:

Onboarding process.

Why this fails: Too vague. The AI application cannot determine when to use this tool, what it does specifically, or what inputs it expects.

Common mistakes

The following table describes mistakes developers make when writing Model Context Protocol (MCP) tool descriptions and how to fix them:

Mistake	Problem	Fix
Too vague	AI application cannot distinguish this tool from similar tools.	Add specific details about what the tool does and when to use it.
Too technical	AI application may misinterpret implementation details as usage instructions.	Write from the perspective of what the tool accomplishes, not how it works internally.
Missing "when to use" context	AI application cannot determine if this tool is appropriate for the user's request.	Add a sentence explaining the scenarios where this tool is the right choice.
Duplicate language across tools	AI application cannot distinguish between similar tools.	Make each description unique by emphasizing what differentiates each tool.
Describing internal behavior	AI application does not need to know about process nodes or expression logic.	Focus on inputs, outputs, and purpose—not implementation.

Test your descriptions

To verify that an AI application selects the right Model Context Protocol (MCP) tool based on your description:

Connect an AI application to Appian MCP Server in a development environment.
Ask natural language questions that match your tool's intended use case.
Confirm the AI application selects your tool and provides appropriate inputs.
Ask questions that are similar but not appropriate for your tool. Confirm the AI application does not select your tool incorrectly.
If the AI application makes the wrong selection, revise the description to better differentiate your tool's purpose and use cases.

Guidelines for tool descriptions

Follow these guidelines when writing Model Context Protocol (MCP) tool descriptions:

Be specific. State exactly what the tool does and returns, not a general category.
Include "when to use" context. Explain the scenario or trigger that makes this tool the right choice.
Mention key inputs. Briefly describe what inputs the tool expects, especially when parameter names are ambiguous.
Use plain language. Write as if explaining to a colleague who knows your business domain but not your Appian implementation.
Keep it concise. Two to four sentences. Longer descriptions add noise without improving selection accuracy.
Differentiate from similar tools. If you have multiple tools in the same domain, emphasize what makes each one unique.
Avoid implementation details. Do not describe process nodes, expression logic, or internal architecture.

Feedback

Was this page helpful?