Improve API Design Guidelines for MCP/Agent readiness

[rartych]

Problem description
As proposed in camaraproject/Governance#210 Commonalites are responsible for CAMARA API Design Guide enhancements with MCP-friendly documentation requirements (AI-readable descriptions, consistent parameter naming, actionable error messages)

Possible evolution

• Analyse best practices for generating MCP tools from OpenAPI specifications
• Propose improvements to guidelines documents

Alternative solution

Additional context
CAMARA + MCP Position Paper

[rartych]

In order to bootstrap our discussion I asked Claude.ai for OpenAPI Design Best Practices for MCP Clients and Agentic AI,
Here is the full report: openapi-agentic-ai-best-practices.md

It is a bit biased by the context of my previous conversations, but the proposed checklist is worth consideration:

Quick-Reference Checklist

Use this checklist when reviewing an OpenAPI specification for agentic compatibility:

Descriptions

• info.description contains a purpose summary and typical usage flow.
• Every operation has a description covering what, when, returns, and side effects.
• Every parameter has a description explaining expected value and effect.
• Every schema property has a description with units, ranges, and business meaning.

Naming

• All operationId values are verb-prefixed and resource-specific.
• No noun-only or path-derived operationId values.
• Disambiguating names used for similar operations with different inputs.

Schema

• All properties have explicit type.
• format applied to date/time, URI, email, UUID, and IP fields.
• enum used for all constrained string value sets.
• minimum/maximum/maxLength applied to bounded numeric and string fields.
• oneOf/anyOf variants are self-contained (do not require parent schema context).
• Working example provided for each operation and complex schema.

Operations

• Non-idempotent POST operations support Idempotency-Key.
• DELETE returns 200 (with body) or 204 on success, 404 on unknown ID.
• Total number of parameters per operation is ≤ 10 (target ≤ 4).

Errors

• All operations document 400, 401, 403, 404, 429, 5xx responses.
• Error responses use RFC 9457 Problem Details format.
• 409 conflict conditions are precisely described.
• 429 documents Retry-After header.

Auth

• Only agent-compatible auth flows are used (client credentials, API key, JWT).
• Token acquisition endpoint is documented in securitySchemes.

Discoverability

• Spec is served at /.well-known/openapi.json or /openapi.json.
• Multi-step workflows are described either in info.description or via Arazzo.

[Kevsy]

Thanks @rartych -good list to start discussions!

I don't agree with this one:

• Spec is served at /.well-known/openapi.json or /openapi.json.

This is not useful or scalable, because:
1./.well-known/openapi.json is not an official IANA-registered well-known URI, and
2. forcing everyone to deploy at a fixed location (/openapi.json) is a constraint

But RFC 9727 solves this by defining a standard API discovery mechanism:

• /.well-known/api-catalog is an official IANA-registered well-known URI .
• GET example.com/.well-known/api-catalog will return a linkset of the definitions, endpoints and metadata for all of example.com's APIs.
• The location of each API can be the decision of the API provider.

The API Provider just needs to publish /.well-known/api-catalog and point it to the linkset that is specified in the RFC, making it easier for agents and human developers to find their APIs, what they are for, and how to use them. This makes discovery of the OAS/Arazzo files easier in the MCP server development.