MCP Core Concepts

Tools

Tools are executable functions that LLMs can invoke to perform actions or retrieve dynamic information. They represent the primary way LLMs interact with external systems through MCP.

Tool Structure

Each tool is defined with:

type Tool = {
  name: string;
  description?: string;
  inputSchema: {
    type: "object",
    properties: { ... }
  },
  annotations?: {
    title?: string;
    readOnlyHint?: boolean;
    destructiveHint?: boolean;
    idempotentHint?: boolean;
    openWorldHint?: boolean;
  }
}

Every API endpoint could be an MCP tool though developers must consider context window limits since all tool schemas consume tokens.

Tool Patterns

• System operations: Execute commands, manage files, control processes. Examples include running build scripts, managing Docker containers, or modifying system configurations based on user requests.

• API integrations: Wrap external services like Jira, Linear, or CRM systems. These tools translate natural language requests into proper API calls with authentication and error handling.

• Data processing: Transform, analyze, or generate content. Tools might parse CSV files, generate reports, compress images, or convert between data formats.

Implementation guidelines

• Keep tool operations focused and atomic. A tool should do one thing well—prefer "create_user" and "update_user" as separate tools over a generic "manage_user" tool with complex branching logic.

• Provide detailed descriptions with examples for complex tools. Include sample inputs in the description like "Use format: YYYY-MM-DD for dates" to help the LLM invoke tools correctly.

• Use annotations to convey tool behavior (destructive, idempotent, etc.). These hints help clients present appropriate warnings or handle tools differently based on their impact.

• Implement comprehensive input validation. Check data types, ranges, formats, and business logic constraints before executing operations to prevent errors and improve security.

• Return errors as part of the result object, not protocol errors. This allows the LLM to see and potentially recover from errors rather than having the conversation fail completely.

• Consider implementing progress reporting for long operations. Use progress notifications to keep users informed during multi-step processes or time-consuming operations.

• Design tools to be model-friendly with clear parameter names. Use descriptive names like "repository_url" instead of "repo" and avoid abbreviations that might confuse the model.

Security considerations

• Validate all inputs against the schema. Never trust input from the LLM—enforce type checking, length limits, and format validation to prevent injection attacks.

• Sanitize file paths and system commands. Use allowlists for commands, resolve relative paths, and never pass user input directly to shell commands without proper escaping.

• Implement appropriate authorization checks. Verify the user has permission to perform the requested operation, especially for tools that modify data or access sensitive resources.

• Rate limit resource-intensive operations. Protect against accidental or intentional resource exhaustion by limiting how often expensive operations can be called.

• Never expose sensitive information in error messages. Return generic errors to the LLM while logging detailed errors server-side to prevent information disclosure vulnerabilities.