Tool Definitions from API Operations

Summary

Every generated tool has three fields - name, description, and input schema - and each maps mechanically from one OpenAPI operation. This page covers only that mapping: how an operation's operationId, summary, parameters, request body, and responses become a tool definition. The portable rules for writing good names, descriptions, schemas, and curated tool sets are not API-specific and live in the Tool Design section - this page links there rather than repeating them.

• operationId → tool name
• summary / description → tool description
• parameters + requestBody schema → input schema
• 2xx response schema → output schema
• x-agent-* extensions → MCP annotations

Operation-to-Tool Mapping

When a framework ingests your OpenAPI spec, it generates one tool per operation using this mapping:

Because the generated name and description come straight from operationId, summary, and description, spec quality is tool quality. A vague summary or description becomes a vague routing prompt; a missing operationId breaks tool generation entirely. See OpenAPI for Agents for the spec-authoring rules that make this mapping produce good tools.

Worked Example

This operation:

paths:
  /orders/{orderId}:
    get:
      operationId: get_order
      summary: Get an order by ID
      description: >
        Retrieves full details for a single order including line items and
        shipping status. Use when you have an order ID. For searching orders,
        use search_orders instead.
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
          description: The order identifier returned by list_orders or create_order
      responses:
        "200":
          description: The order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"

Generates this tool definition:

{
  "name": "get_order",
  "description": "Retrieves full details for a single order including line items and shipping status. Use when you have an order ID. For searching orders, use search_orders instead.",
  "inputSchema": {
    "type": "object",
    "required": ["orderId"],
    "properties": {
      "orderId": {
        "type": "string",
        "description": "The order identifier returned by list_orders or create_order"
      }
    }
  }
}

Extensions and Annotations

Agent-facing behavior that has no native OpenAPI field is carried by x-agent-* extensions on the operation and translated into MCP annotations (readOnlyHint, idempotentHint, destructiveHint) at generation time. The extension-to-annotation table lives in OpenAPI Extensions; the semantics of the annotations themselves are covered in Tool Design: Idempotency and Safety.

Generating the Tools

Turning a spec into a running MCP server - generator choice, transport, and lifecycle - is covered in MCP Servers: Auto-Generation from OpenAPI. For Bedrock Agents, the same OpenAPI document is uploaded directly as an action group rather than compiled into individual tools.

Checklist

Before generating tools from your API:

• Every operation you want exposed has a unique verb_noun operationId
• Each description reads as an agent trigger condition, not human documentation
• Path and query parameters carry description and constraints
• Request bodies reference reusable component schemas
• 2xx responses declare a schema so output types survive generation
• Destructive or non-idempotent operations carry the matching x-agent-* extension
• You expose a curated subset, not one tool per endpoint (see Tool Curation)

Related Pages

• Tool Design - the cross-framework rules for names, descriptions, schemas, safety, and curation
• Naming and Descriptions - write operationId and summary that route correctly
• OpenAPI for Agents - the spec that generates these tool definitions
• OpenAPI Extensions - x-agent-* hints for confirmations, idempotency, and destructive actions
• Arazzo Workflows - composing operations into multi-step workflow tools
• MCP Servers: Auto-Generation - turning the spec into a running server