| @@ -101,8 +101,35 @@ | ||
| 101 | 101 | - `execute()` — returns the tool-result value (array, string, or any MCP-compatible type). |
| 102 | 102 | |
| 103 | 103 | ## Registered abilities |
| 104 | 104 | |
| 105 | +### Identifying a media | |
| 106 | + | |
| 107 | +`imagify/optimize-media`, `imagify/restore-media` and `imagify/get-media-status` accept three | |
| 108 | +interchangeable identifiers, so a caller that only knows the file name or the URL of an image does | |
| 109 | +not have to look its attachment ID up first. None of the three is required on its own — exactly one | |
| 110 | +must be supplied (hence `no*` in the input tables): | |
| 111 | + | |
| 112 | +| Input | Resolution | | |
| 113 | +|-------|------------| | |
| 114 | +| `media_id` | Used as-is. | | |
| 115 | +| `media_url` | `attachment_url_to_postid()`. Next-gen and thumbnail URLs (`hero-300x200.jpg.webp`) fall back to a file-name lookup on the original. | | |
| 116 | +| `media_filename` | Exact, case-insensitive match on the base name of the `_wp_attached_file` meta. A full relative path (`2026/08/hero.jpg`) is accepted too. | | |
| 117 | + | |
| 118 | +`media_id` wins over `media_url`, which wins over `media_filename`. A `media_id` of `0` or less is | |
| 119 | +treated as absent, so the next identifier is tried. | |
| 120 | + | |
| 121 | +Errors are explicit and actionable rather than best-effort: | |
| 122 | + | |
| 123 | +| Error code | When | | |
| 124 | +|------------|------| | |
| 125 | +| `imagify_missing_media_identifier` | None of the three inputs was usable. | | |
| 126 | +| `imagify_media_not_found` | The URL or file name matches nothing in the library. | | |
| 127 | +| `imagify_ambiguous_media_filename` | Several attachments share the file name. The message lists the matching IDs so the caller can retry with `media_id`. | | |
| 128 | + | |
| 129 | +Resolution lives in `Imagify\Abilities\MediaResolver::resolve_id()`, which returns an attachment ID | |
| 130 | +or a `WP_Error`. Each ability turns that `WP_Error` into its own `status: "error"` output shape. | |
| 131 | + | |
| 105 | 132 | ### Credit confirmation flow |
| 106 | 133 | |
| 107 | 134 | `imagify/optimize-media`, `imagify/bulk-optimize`, and `imagify/generate-missing-nextgen` consume |
| 108 | 135 | Imagify quota, so each one is gated by `Imagify\Abilities\AbstractAbility::guard_credit_confirmation()` |
| @@ -240,9 +267,11 @@ | ||
| 240 | 267 | **Input schema:** |
| 241 | 268 | |
| 242 | 269 | | Field | Type | Required | Description | |
| 243 | 270 | |-------|------|----------|-------------| |
| 244 | -| `media_id` | integer | yes | WordPress attachment ID. | | |
| 271 | +| `media_id` | integer | no* | WordPress attachment ID. | | |
| 272 | +| `media_filename` | string | no* | File name of the media, for example `hero-banner.jpg`. | | |
| 273 | +| `media_url` | string | no* | Absolute URL of the media. | | |
| 245 | 274 | | `optimization_level` | integer (0–2) | no | Overrides the global setting. 0 = normal, 1 = aggressive, 2 = ultra. | |
| 246 | 275 | | `confirm` | boolean | no | Set to `true` to execute after reviewing the credit-consumption preview returned by a prior call without this flag. Defaults to `false`. See [Credit confirmation flow](#credit-confirmation-flow). | |
| 247 | 276 | |
| 248 | 277 | **Output schema:** |
| @@ -271,9 +300,11 @@ | ||
| 271 | 300 | **Input schema:** |
| 272 | 301 | |
| 273 | 302 | | Field | Type | Required | Description | |
| 274 | 303 | |-------|------|----------|-------------| |
| 275 | -| `media_id` | integer | yes | WordPress attachment ID to restore. | | |
| 304 | +| `media_id` | integer | no* | WordPress attachment ID to restore. | | |
| 305 | +| `media_filename` | string | no* | File name of the media, for example `hero-banner.jpg`. | | |
| 306 | +| `media_url` | string | no* | Absolute URL of the media. | | |
| 276 | 307 | |
| 277 | 308 | **Output schema:** |
| 278 | 309 | |
| 279 | 310 | | Field | Type | Description | |
| @@ -382,9 +413,11 @@ | ||
| 382 | 413 | **Input schema:** |
| 383 | 414 | |
| 384 | 415 | | Field | Type | Required | Description | |
| 385 | 416 | |-------|------|----------|-------------| |
| 386 | -| `media_id` | integer | yes | WordPress attachment ID. | | |
| 417 | +| `media_id` | integer | no* | WordPress attachment ID. | | |
| 418 | +| `media_filename` | string | no* | File name of the media, for example `hero-banner.jpg`. | | |
| 419 | +| `media_url` | string | no* | Absolute URL of the media. | | |
| 387 | 420 | |
| 388 | 421 | **Output schema:** |
| 389 | 422 | |
| 390 | 423 | | Field | Type | Description | |
| @@ -396,9 +429,9 @@ | ||
| 396 | 429 | | `webp_available` | boolean | `true` when a WebP version of the full-size image has been generated. | |
| 397 | 430 | | `avif_available` | boolean | `true` when an AVIF version of the full-size image has been generated. | |
| 398 | 431 | | `error_message` | string \| null | Human-readable error message when `status` is `"error"`. `null` otherwise. | |
| 399 | 432 | |
| 400 | -**Error behaviour:** If `media_id` is `0` or negative, or the attachment does not exist in the database, returns `status: "error"` with a descriptive `error_message`. | |
| 433 | +**Error behaviour:** If no identifier resolves to an attachment, returns `status: "error"` with a descriptive `error_message`. See [Identifying a media](#identifying-a-media). | |
| 401 | 434 | |
| 402 | 435 | ### `imagify/get-nextgen-coverage` |
| 403 | 436 | |
| 404 | 437 | Registered by `Imagify\Abilities\GetNextgenCoverage`. Returns the number of optimized images that are missing a next-gen (WebP/AVIF) version, and the next-gen format currently configured in Imagify settings. |
