I want to suggest we align our internal naming conventions with the established MCP protocol standards to reduce developer cognitive load and maintain consistency across the systems.

Current approach:

• Internally: read_only, destructive, idempotent
• MCP: readOnlyHint, destructiveHint, idempotentHint

Suggested approach:
Since MCP is a well-established protocol with defined conventions, I think we should adopt the MCP naming directly in our abilities API:

• Use: readOnlyHint, destructiveHint, idempotentHint internally
• This eliminates the need for translation in the MCP adapter
• Developers working with both our API and MCP won't need to context-switch between naming conventions
• Minimizes developer confusion when working across both systems

Additional consideration - Instructions handling:
For the instructions field, since MCP uses the tool description as instructions, we can handle this in the MCP adapter by appending our instructions content to the description field.

The counterpoint would be that WordPress uses snake case convention for naming properties. REST API is a good reflection of that. It's also inconvenient with JavaScript that uses camel case similarly to the MCP protocol. Sometimes, we even mix the two when functionality spans all layers, as with block types that also support the JSON format, which again uses camel case.

@felixarntz, and @swissspidy, what are your thoughts on that aspect?

+1 on aligning with WordPress's snake case convention:

• For the reason @gziolo mentioned: We shouldn't discard WordPress Coding Standards when it's convenient :)
• Another counterpoint is that this is the Abilities API which was from the beginning decided to be decoupled from MCP, and rightfully so.

IMO it's perfectly reasonable to have a translation layer in place as part of the MCP adapter, we shouldn't change the Abilities API to tie in particularly well with MCP when it leads to other problems.

Aside: I do agree it's painful to deal with snake_case from the server in the client-side JavaScript world where everything is camelCase. My recommendation for that reason is to use single-word names (like readonly, destructive, idempotent) wherever possible, as those would be both valid snake_case and valid camelCase. But obviously this is not the problem discussed here - it doesn't allow us to align with the MCP naming.

Happy to rename from read_only to readonly. I'm not even 100% sure whether "read-only" is the ultimate correct English spelling 😄 I definitely saw many times readonly in the context of programming, for example, in TypeScript.

Whatever you decide to do is ok with me. Also, adapting those keys to the MCP standards is not a big problem.

I also understand your points on WP coding standards and the abilities-api being decoupled from MCP.

One thing I want to avoid when creating abilities for MCP usage:

$annotations = array(
    'read_only' => true, // translated to readOnlyHint
    'destructive' => false, // translated to destructiveHint
    'idempotent' => true, // translated to idempotentHint
    'openWorldHint' => false,
    'lastModified' => '...',
    'title' => '...',
    'audience' => '...',
    'priority' => '...',
)

This is inconsistent, non-standard, and ugly.

So, what do you think we should do to avoid this situation?

Completely agree, we shouldn't have inconsistencies like this.

Where does this example list of identifiers come from? As far as this PR is concerned, I think we can use readonly to work around the difference between snake_case and camelCase.

If there are terms where we need multi-word identifiers, I'd say we need to use snake_case if their source of truth is on the server (i.e. in PHP).

If in some JavaScript use-cases we need to translate stuff to be camelCase, we could probably do that consistently as well.

I agree with @felixarntz. We shouldn't build anything in Abilities around the MCP standard. The MCP Adapter is a consumer of the Abilities API and should handle any translations and such needed to work. Any parameters added by the MCP Adapter should follow the pattern established here.

As a grammatical note, it kills me every time I see "readonly" in various contexts. We're just lying to ourselves. 😆

The MCP annotations are documented here:
https://modelcontextprotocol.io/specification/2025-06-18/schema#annotations
https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations

I used the same docs to shape basic needs for abilities based on the discussion in #62.

Renamed read_only key to readonly, and adjusted docs to use "read-only" form in 9f3a00c.