AI-Friendly Operation Catalog

In order to understand how an API can be used, a human developer can read code, documentation, and examples. An AI client application needs that understanding as well, but in the form of structured metadata. Every operation, such as Bank.MakeDeposit, needs a machine-readable descriptor that explains what the operation does and what input it expects. In many modern AI-oriented systems, such operations are commonly called tools.

Tool Descriptor

A tool descriptor is a JSON document that describes an operation. It includes the operation name, a description of what it does, whether it is read-only or changes state, and a JSON Schema that defines the expected input parameters. For example, the following descriptor describes a Bank.MakeDeposit operation that deposits money into an existing bank account and returns the new balance:

{
  "name": "Bank.MakeDeposit",
  "description": "Deposits money into an existing bank account and returns the new balance.",
  "isReadOnly": false,
  "inputSchema": {
    "type": "object",
    "properties": {
      "accountNumber": {
        "type": "string",
        "description": "Bank account number receiving the deposit."
      },
      "amount": {
        "type": "number",
        "description": "Amount of money to deposit.",
        "minimum": 0.01
      }
    },
    "required": [ "accountNumber", "amount" ]
  }
}

Why Input Schema Matters

Input schema gives the AI client enough information to construct a valid call. It describes field names, types, required properties, validation hints, and descriptions.

Read-Only Versus Write Tools

Tool metadata should also indicate whether an operation changes state. A shipment search is read-only. A bank deposit is not. This distinction is important for approval flows, auditing, and safe AI automation.

From API to Capability

An AI-friendly catalog transforms an API from a set of endpoints into a set of capabilities. The AI can inspect the catalog, understand available tools, and invoke the appropriate operation.

 

Table of Content Operation-Oriented APIs and AI Tools Previous: Swagger and RPC Discoverability Next: MCP Concepts Without the Mystery

 

---

Business Process Programming in .Net
© 2004–2026 Laskarzhevsky Software Inc.
Unless otherwise noted, the content of this website is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
Code examples are provided under the MIT License.
You are free to share and adapt the material provided that appropriate credit is given and any modifications are clearly indicated.
The information provided on this website is for educational purposes only.
The author and publisher make no warranties regarding the completeness or suitability of the information and are not responsible for any damages resulting from its use.