Skip to main content
Glama
Sign In

Royally

by io.royally
OverviewDiscussionsAdmin

mcp-easy-ai__wp_list_media

Read-only

Lists media library items (per_page 10 by default, 100 at most; page or offset). Filters: search, media_type (image/video/audio/application), mime_type (one exact type, e.g. "image/png"), author, author_exclude, parent (the post an item is attached to; 0 = unattached only) or parent_exclude (0 = leave unattached items out), include or exclude (item IDs), after / before (upload date, ISO 8601), status (inherit by default; private, trash, a comma-separated list, or any = inherit and private), and taxonomy_filters / taxonomy_exclude (taxonomy slug → term IDs, e.g. {"mlo-category": [12]} for a media folder; attachment taxonomies shown in the REST API only — find them with wp_get_taxonomies, their terms with wp_list_terms), joined by taxonomy_relation (AND by default, or OR). Sort with orderby (date by default; id, title, slug, modified, author, parent, include) and order (desc by default); items that tie are ordered by ID, so pages never repeat or skip one. context e… Through Royally: its server marks it read-only, so it runs straight away.

Input Schema

NameRequiredDescriptionDefault
pageNoPage number for pagination.
afterNoOnly media uploaded on or after this ISO 8601 date-time (e.g. "2026-01-01T00:00:00").
orderNoOrder direction.desc
authorNoUploader/author user ID to filter by.
beforeNoOnly media uploaded on or before this ISO 8601 date-time (e.g. "2026-12-31T23:59:59").
offsetNoSkip this many matching items. Replaces page: send one or the other.
parentNoOnly items attached to this post ID. 0 lists unattached items only. Not with parent_exclude.
searchNoSearch query to filter media items.
statusNoinherit (default: every ordinary media item), private, trash (only with MEDIA_TRASH), a comma-separated list of those, or any (inherit and private, as WP_Query reads any for attachments). A status other than inherit needs edit_posts.
contextNoview (default): items you can read. edit: only items you can edit (needs edit_posts).view
excludeNoIDs to leave out. Not with include: WordPress ignores an exclusion when include is given.
includeNoOnly these IDs (non-empty). With orderby "include", results keep this order.
orderbyNoField to order results by. include keeps the order of `include`.date
site_idNoSite to run this tool on: 8ef2e52b-bd07-4671-a363-ebe8b480b65c (https://demo.royalplugins.com)
per_pageNoNumber of media items per page (1-100).
mime_typeNoMIME type to filter by (e.g. image/jpeg, application/pdf).
media_typeNoMedia type to filter by.
raw_columnsNoEdit context only. Each item also carries raw: every database column as WordPress stores it (ID, post_author, post_date, post_date_gmt — 0000-00-00 00:00:00 for an unscheduled draft —, post_content, post_title, post_excerpt, post_status, comment_status, ping_status, post_password, post_name, to_ping, pinged, post_modified, post_modified_gmt, post_content_filtered, post_parent, guid, menu_order, post_type, post_mime_type, comment_count, filter). Default false.
author_excludeNoArray of author user IDs to EXCLUDE from results.
parent_excludeNoLeave out items attached to these post IDs (0 leaves out unattached items). Not with parent, which WordPress lets override it.
taxonomy_excludeNoExclude items assigned to these terms; same shape as taxonomy_filters.
taxonomy_filtersNoOnly items assigned to these terms: an object keyed by taxonomy slug whose values are arrays of term IDs, e.g. {"mlo-category": [12, 15]}. Only taxonomies registered on attachments and exposed in the REST API are accepted; a JSON string of the same object is also accepted.
taxonomy_relationNoHow multiple taxonomies in taxonomy_filters combine.AND

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description largely restates that ('its server marks it read-only, so it runs straight away'). It does add genuinely useful behavioral context not in the annotations: `status` beyond inherit needs edit_posts, `context: edit` needs edit_posts, and page stability via ID tie-breaking. It says nothing about the response shape, pagination totals, or `raw_columns` cost (Edit context only).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single run-on mega-sentence enumerating every parameter, and it is truncated mid-thought ('`context` e… Through Royally: its server marks it read-only'). It is not front-loaded: the core purpose and the pagination model are buried under an unbroken parameter dump, and the garbled ending harms trust.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 23-parameter tool with no output schema, the description covers filtering semantics well but is missing the return shape (item fields, whether paging metadata is returned) and the truncated tail leaves content undefined. Permission notes are present, so it is adequate-but-incomplete rather than deficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and nearly every clause in the description duplicates a schema field description almost verbatim (per_page defaults, media_type values, include/exclude interactions). The one piece of added meaning is the tie-breaking note ('items that tie are ordered by ID, so pages never repeat or skip one'), which goes beyond the schema. Baseline 3 is appropriate given the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Lists media library items', then enumerates the filter surface. An agent can tell this is a paginated, filterable media listing without opening the schema. It does not, however, name or differentiate itself from close siblings such as wp_find_media or wp_get_media.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to reach for this tool versus wp_find_media, wp_get_media, or wp_count_media. The only routing hints are internal (`wp_get_taxonomies`, `wp_list_terms`) telling the agent how to discover taxonomy slugs, which is parameter support rather than tool selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Royally toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources