When designing OpenAPI specifications for MCP tools, it is important to follow certain principles that ensure clarity and consistency while ensuring usability. These principles help create predictable tool behavior, improve integration, and make the specification easier to maintain. The following topic describes the fundamental principles that help you design robust and maintainable OpenAPI specifications.

The following table lists the key principles, explains why they matter, and provides examples:
Principle Why it matters Example
Unique operationId per operation MCP tool IDs map one-to-one to operationId getCustomerById, listCustomers
Descriptive summary and rich description Tool list shows summary; description becomes long help Summary: Fetch a customer; Description: business rules, rate limits
Explicit request and response schemas Enables clear input/output contracts requestBody → $ref: '#/components/schemas/CreateOrderRequest'
Use title in component schemas Provides readable names in generated helper tools title: Customer
Every object property has a type Avoids defaulting to untyped any type: string or type: integer
Mark required fields using required array Distinguishes mandatory versus optional fields required: [id, name]
Enumerate finite sets with enum and description Lets agents constrain values status: {enum: [OPEN, CLOSED]}
Explain side effects in description Tool consumers can reason about writes Creates invoice; idempotent by clientProvidedId
Version the specification (info.version) Provides traceability and cache invalidation 1.3.0
Avoid generic names Improves clarity of tool list Prefer getOrderInvoices over doList