---
title: "Tool Definitions from API Operations"
description: "Mapping OpenAPI operations to agent tool definitions; universal tool-design guidance lives in Tool Design"
url: "https://agentsurface.dev/docs/api-surface/tool-definitions"
lastVerified: 2026-09-24
lastModified: 2026-09-25T05:46:01.000Z
---



## Summary [#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](/docs/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 [#operation-to-tool-mapping]

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

| OpenAPI element           | Tool field    | Notes                                                                  |
| ------------------------- | ------------- | ---------------------------------------------------------------------- |
| `operationId`             | `name`        | Must be globally unique and `verb_noun` - it becomes the function name |
| `summary` + `description` | `description` | The agent's routing prompt; write it as trigger conditions, not docs   |
| path/query `parameters`   | input schema  | Flattened into the schema's `properties`                               |
| `requestBody` schema      | input schema  | Merged with parameters into one flat object                            |
| `2xx` response schema     | output schema | Enables downstream tools to reason over typed results                  |
| `x-agent-*` extensions    | annotations   | Confirmation, idempotency, destructive hints                           |

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](./openapi-for-agents) for the spec-authoring rules that make this mapping produce good tools.

## Worked Example [#worked-example]

This operation:

```yaml
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:

```json
{
  "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 [#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](./openapi-extensions); the semantics of the annotations themselves are covered in [Tool Design: Idempotency and Safety](/docs/tool-design/idempotency-and-safety).

## Generating the Tools [#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](/docs/mcp-servers/auto-generation). For Bedrock Agents, the same OpenAPI document is uploaded directly as an action group rather than compiled into individual tools.

## Checklist [#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](/docs/tool-design/tool-curation))

## Related Pages [#related-pages]

* [Tool Design](/docs/tool-design) - the cross-framework rules for names, descriptions, schemas, safety, and curation
* [Naming and Descriptions](/docs/tool-design/naming-and-descriptions) - write `operationId` and `summary` that route correctly
* [OpenAPI for Agents](./openapi-for-agents) - the spec that generates these tool definitions
* [OpenAPI Extensions](./openapi-extensions) - `x-agent-*` hints for confirmations, idempotency, and destructive actions
* [Arazzo Workflows](./arazzo-workflows) - composing operations into multi-step workflow tools
* [MCP Servers: Auto-Generation](/docs/mcp-servers/auto-generation) - turning the spec into a running server