Abilities API Granularity vs. REST Endpoints

[mateuswetah]

Hi folks 👋

I’ve been experimenting with the new Abilities API, and I’d love to get some feedback from you about how granular abilities should be compared to REST endpoints.

Why? Well, as I try to understand it, the Abilities API looks very similar to the REST API in several ways:

• Both use JSON Schema for input/output (I'm using openapi in my REST).
• Both have execute callbacks that validate input, check permissions, and return data.
• Many of the things I’d register as an ability (e.g. searching items, exporting data, generating links) already exist in some form as REST endpoints.

Yet I understand why the Abilities API must exist! Separating that layer from the MCP Adapter and keeping things generic enough to be usable by agents (either AI or the Command Palette, that will be super cool). But still I want to avoid two pitfalls:

1. Registering too many low-level abilities and essentially duplicating my REST API (or making a big wrapper around it).
2. Registering too few big abilities that are too specialized, to the point that agents won't know how to compose more complex stuff if things don't fit the input parameters.

For example, in a plugin I work on we have a custom REST controller for “collections” (basically a custom post type). That REST API already exposes stuff like:

• GET /collections (list collections)
• GET /collections/:id (collection details, including permalink)
• GET /items?collection_id=ID (list items inside a collection)
• POST /exporters/:exporter_type?collection_id=ID Triggers async workflows to export a collection, returns a job id.

When I think about registering abilities for these, I get stuck on questions of granularity.

Should abilities be very small/atomic, like REST endpoints?

Example:

• get-collection-info (input: ID, output: title + link)
• open-collection (input: ID, output: admin edit URL)

This makes abilities predictable and composable, but often requires multiple calls for a single workflow (list → pick ID → open).

Or should abilities be more “curated workflows”?

Example:

• export-collection → instead of exposing low-level REST endpoints, this one ability both enqueues the job and returns a job descriptor (job_id, status, check_link).

This feels more “user-action-oriented” and useful for Command Palette / AI agents, but it overlaps less cleanly with REST.

What about overlap with existing fields?

In my example, collections already have a guid field with the public URL. Does it still make sense to have a dedicated open-collection ability, or should get-collection-info just include the link and be enough?

Is the expectation that agents (or clients like the Command Palette) will chain multiple small abilities to reach a goal?

For example:

• User says “Open the Photos collection” →
• Agent calls get-collections → finds ID →
• Agent calls open-collection → gets admin link.

Or should I instead expose a single ability that accepts the collection name and returns the link in one step?

---

To summarize:

• How do you see the line between REST endpoints and Abilities?
• Should abilities lean toward atomic + composable or curated workflows?
• Are there emerging conventions that plugin authors should follow to keep abilities interoperable?

No easy stuff I know, just think this is a nice place to hear from others.

Thanks for any insights 🙏