---
title: "list_subjects: List subjects"
description: "The named identities this account reuses — a character, a location, a product, a prop, a wardrobe."
canonical_url: "https://meetkuro.com/agents/tools/list_subjects/"
updated: 2026-11-03
locale: "en"
tool: "list_subjects"
scopes: ["media.read"]
---

# list_subjects

**List subjects**

The named identities this account reuses — a character, a location, a product, a prop, a wardrobe. Each item carries a `subject` handle the generate tools take as-is: passing it supplies that identity's face and its description together, so you do not have to find a reference file or re-describe it. Check this before list_media. `tags` narrows to the subjects carrying every tag named.

## Scope

- `media.read` — Reads the account: media, uploads, boards, runs, Subjects, models and the balance.

## Behaviour

- **Read-only**: Reads the caller's own account and changes nothing.
- **Stays in the account**: Stays inside the caller's private Kuro account: any media provider it calls acts on Kuro's account, and the result is visible to no one else.
- **Idempotent**: Calling it again with the same arguments has no further effect.

## Inputs

| Name | Type | Required | Details |
| --- | --- | --- | --- |
| `q` | string | no | at most 120 characters |
| `kind` | string | no | one of "character", "location", "product", "prop", "wardrobe" |
| `favorite` | boolean | no | — |
| `tags` | array of string | no | at least 1 item; at most 8 items |
| `order` | string | no | one of "recent", "oldest", "name" |
| `limit` | integer | no | ≥ 1; ≤ 100 |
| `cursor` | string | no | The `next_cursor` of the page before this one. — at most 200 characters |

## Example call

A `tools/call` request with the required arguments only, each a placeholder read off the schema. Replace them before sending.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_subjects",
    "arguments": {}
  }
}
```

## Input schema

As the server sends it in `tools/list`:

```json
{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 120
    },
    "kind": {
      "type": "string",
      "enum": [
        "character",
        "location",
        "product",
        "prop",
        "wardrobe"
      ]
    },
    "favorite": {
      "type": "boolean"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40
      },
      "minItems": 1,
      "maxItems": 8
    },
    "order": {
      "type": "string",
      "enum": [
        "recent",
        "oldest",
        "name"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "type": "string",
      "maxLength": 200,
      "description": "The `next_cursor` of the page before this one."
    }
  },
  "additionalProperties": false
}
```

## Related tools

- [`list_media`](https://meetkuro.com/agents/tools/list_media.md): List ready generations and verified uploads already in the user's account, newest first.
- [`create_storyboard`](https://meetkuro.com/agents/tools/create_storyboard.md): Make a film three ways: from a brief you have written as scenes, from media the account already holds, or from a video you have already analysed.
- [`update_storyboard`](https://meetkuro.com/agents/tools/update_storyboard.md): Change a film's own properties in one call; only the fields you send change.

---

## About Kuro

Kuro is an AI picture studio: prompt-driven images, clips, voice-overs and music, and storyboard-backed films with consistent characters across every scene.

Agents connect over MCP and can generate directly:

```
claude mcp add kuro https://api.meetkuro.com/mcp --transport http
```

The app is at https://app.meetkuro.com and requires an account.

Each guide, model page, comparison and free tool page on this site (not a tool's variants, and not the index pages) has a Markdown twin at its own URL plus `.md`, and so do /benchmarks/, the English /agents/ page (as /agents.md) and the MCP tool reference. Every tool: https://meetkuro.com/agents/tools/