/
2026-05-18 Commonalities MCP Enablement Program Minutes

2026-05-18 Commonalities MCP Enablement Program Minutes

Community Attendees:

@Rafal Artych @Herbert Damker @Sébastien Dewet @ABOUCHI, Aziz @Jan Friman @Masaharu Hattori @Surajj Jaggernath @Leo Chely @Ben Hepworth @Mark Cornall @Nick Venezia

Community Attendees:

@Jesús Peña García-Oliva @pedro.diezgarcia@telefonica.com @Pierre Close Neeraj Dahiya (Tanla) @diego.gonzalezmartinez Mayumi Ohsugi - NTT, Yannick Le Saout (Orange)

LF Staff:

Agenda

The project's Antitrust Policy is linked from the LF and project websites. The policy is important when multiple companies, including potential industry competitors, are participating in meetings. Please review it, and if you have any questions, please contact your company’s legal counsel. Members of the LF may contact Andrew Updegrove at the firm Gesmer Updegrove LLP, which provides legal counsel to the LF.

  • API Design Guide Enhancements

  • Tool Definition Guide

  • Security & Consent Guidance

Minutes

API Design Guide Enhancements

https://github.com/camaraproject/Commonalities/issues/587

  1. Good operationIds

    • https://github.com/camaraproject/Commonalities/issues/623

      • All operationIds must follow the verbNoun pattern in lowerCamelCase

        • When two operations share the same verbNoun, a qualifier must be inserted between verb and noun as verbQualifierNoun or

          verbNounQualifier

      • Use only verbs from the approved list?

      • Should OperationIds must be unique across all OpenAPI documents that will be merged into a single MCP server?

      • operationId length < 64 chars (48 chars name +16 chars prefix)

#

Severity

Rule

Affected today

#

Severity

Rule

Affected today

1

MUST

operationId matches ^[a-z][a-zA-Z0-9]{0,63}$ (codifies camelCase + 64-char vendor ceiling)

5 KYC operations

2

SHOULD

operationId ≤ 48 chars (leaves room for client-injected prefixes)

10 subscription-related operations

3

MUST

<verb><Noun>[<Qualifier>] shape

~14 operations (eSIM, NumberVerification, KYC, verb-only count/query)

4

MUST

No HTTP-method prefix on the verb (excluding get as English verb)

4 operations (postTrafficInfluence family, postServiceCapability)

5

MUST

No version marker (V1, _v1, …)

0 — pure future-protection

6

SHOULD

One read verb per document (within-spec consistency)

7 specs mix get/retrieve or read/retrieve

7

SHOULD

Unique within document

1 spec (WebRTC reuses an op name for its callback)

  1. Decent Descriptions

#

Severity

Rule

Affected today

9

MUST

Operation description present and non-empty

18 operations

10

MUST

Operation description ≠ summary verbatim

26 operations

11

MUST

Operation description self-contained for tool selection (anything an MCP consumer needs to pick and interpret the operation must be reachable without info.description)

Most mature APIs

(existing)

MUST

Property description present — enforce existing rule

1,674 properties

12

SHOULD

Enum descriptions enumerate per-value semantics when values aren't self-evident, using the markdown-bullet format already used by 14.6% of the cohort

345 enums

  1. Clean Schemas

  2. Examples

 

```markdown ## 10. AI and MCP consumer considerations The rules in §5.7.2 and §5.8 above include several requirements that originate from how AI agents — particularly clients of the Model Context Protocol (MCP) — consume OpenAPI specifications. This section explains the reasoning. It is informative; the normative rules are in the referenced sections. ### 10.1 What an MCP client sees When an OpenAPI document is exposed via an MCP server, each operation typically becomes one "tool" in a flat catalog the LLM can choose from. The tool's name is derived from `operationId`. The tool's description is derived from `summary` and/or `description` (varies by bridge). The tool's input schema is derived from the flattened union of path / query / header / body parameters with all `$ref`s inlined. `info.description` is generally NOT surfaced. ### 10.2 Why operationId shape matters Tool names that look structurally similar (e.g. `getX` next to `retrieveX` for similar resources) make the LLM less reliable at picking the correct one. The within-spec consistency rule and the verbNoun shape requirement address this. Tool names also have hard ceilings imposed by vendor APIs (64 chars on Anthropic and OpenAI; effectively less after client prefixing). The length limits in §5.7.2 reflect those ceilings. ### 10.3 Why description content matters A tool description is the LLM's only signal for selecting the operation. Descriptions that paraphrase the summary, or that lean on `info.description` for content, lose that signal at the bridge boundary. The content checklist in §5.7.2 helps ensure each description is sufficient by itself. ### 10.4 What lives where | Information | Location | Reaches MCP client? | |---|---|---| | Operation purpose | Operation `description` | Yes | | Parameter meaning | Parameter `description` | Yes | | Format constraint | Schema `description` (often via `$ref`) | Yes (bridges inline) | | Enum value meanings | Schema `description` of the enum | Yes | | Result branching | Response schema property `description` | Yes | | Authentication overview | `info.description` § Authorization | No (deployment-specific) | | Additional error responses | `info.description` § Additional errors | No (deployment-specific) | | Multi-SIM, identification-from-token rules | `info.description` — but MUST also be reflected on the operations they affect | Yes, if mirrored to operations |

Tool Definition Guide

https://github.com/camaraproject/Commonalities/issues/588

 

Security & Consent Guidance

https://github.com/camaraproject/IdentityAndConsentManagement/issues/347

 

AOB


Concern

Human-only API docs

MCP-targeted

Concern

Human-only API docs

MCP-targeted

Cross-tool disambiguation

Implicit (humans read the section header / TOC)

Must be inline in description — e.g. "use this when…; if you only need IDs, use listX instead" (Speakeasy guide)

When NOT to use

Rarely written

Anthropic explicitly recommends this be in every description (Define tools)

Discovery hints between tools

A human reads the spec linearly

Tool needs to explicitly say "to obtain an X, first call Y" because the LLM doesn't browse (Speakeasy example)

Negative / boundary constraints

"ticker must be valid"

"ticker must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ" (Claude docs example) — explicit, exhaustive

Param-name precision

"user" might be fine in context

user_id, customer_id, device_phone_number — disambiguation required even when intuitive to humans (Anthropic Writing tools)

Length budget

No hard cap

64-char combined name budget after client prefixing; descriptions consume scarce input tokens (Claude tool-use overview)

Auth flows

Detailed in security block

Invisible to the LLM unless surfaced in description

Response post-conditions

Tested by humans

"What you can rely on the tool returning" should be in the description so the LLM knows whether to chain another call

Implicit conventions

OK to assume context

Stated explicitly — e.g. "default unit is meters", "date format is RFC 3339" — folded into description text rather than only in format/example keywords

Action items