# Tools and Workflow
Complete reference for the four LottieFiles MCP workbench tools, plus resources, prompts, example usage, and rate limits.

The LottieFiles MCP server exposes a compact **GraphQL workbench**: four tools that let your assistant discover the LottieFiles GraphQL schema and execute operations against it. Schema discovery runs against a cached snapshot, so browsing is fast and never touches your data — only `graphql_execute` reaches the live API.

## The Four Tools

| Tool              | What it does                                                                           | Access     |
| :---------------- | :------------------------------------------------------------------------------------- | :--------- |
| `operations_list` | Browse the GraphQL root operations, filtered by kind, category, or risk                | Read-only  |
| `schema_search`   | Search operations, types, fields, enums, and inputs by keyword                         | Read-only  |
| `schema_details`  | Get full detail for one named operation or type — arguments, input shapes, enum values | Read-only  |
| `graphql_execute` | Run a complete GraphQL query or mutation against LottieFiles                           | Read/write |

### operations\_list

Lists GraphQL root operations from the schema catalog. Use it first to get an inventory of what the API can do.

| Parameter  | Type                                                       | Description                                                             |
| :--------- | :--------------------------------------------------------- | :---------------------------------------------------------------------- |
| `kind`     | `QUERY` \| `MUTATION` \| `SUBSCRIPTION`                    | Filter by operation kind                                                |
| `category` | `string`                                                   | Filter by category (see the `lottiefiles-schema://categories` resource) |
| `query`    | `string`                                                   | Filter names and descriptions by keyword                                |
| `risk`     | `read` \| `write` \| `destructive` \| `billing` \| `admin` | Filter by risk classification                                           |
| `limit`    | `number`                                                   | Page size, 1–100 (default 25)                                           |
| `cursor`   | `string`                                                   | Pagination cursor from a previous call                                  |

### schema\_search

Searches the whole cached schema — operations, types, fields, enums, and input objects. An empty query returns a paginated inventory.

| Parameter      | Type                                                                              | Description                                                  |
| :------------- | :-------------------------------------------------------------------------------- | :----------------------------------------------------------- |
| `query`        | `string`                                                                          | Search text (default `""`)                                   |
| `kind`         | `QUERY` \| `MUTATION` \| `SUBSCRIPTION` \| `TYPE` \| `FIELD` \| `ENUM` \| `INPUT` | Restrict the result kind                                     |
| `detail_level` | `name` \| `summary` \| `full`                                                     | Set how much detail each result includes (default `summary`) |
| `limit`        | `number`                                                                          | Page size, 1–100 (default 10)                                |
| `cursor`       | `string`                                                                          | Pagination cursor from a previous call                       |

### schema\_details

Returns exact details for one operation, type, input, or enum by name: full GraphQL type strings, arguments, nested input shapes, enum values, and pagination hints. Use it before writing a query so arguments and selections are correct on the first try.

| Parameter              | Type                | Description                                  |
| :--------------------- | :------------------ | :------------------------------------------- |
| `name`                 | `string` (required) | Operation or type name                       |
| `include_fields`       | `boolean`           | Include field lists (default `true`)         |
| `include_input_fields` | `boolean`           | Include input object shapes (default `true`) |
| `include_enum_values`  | `boolean`           | Include enum values (default `true`)         |

### graphql\_execute

Executes a complete GraphQL document against the LottieFiles API with your account's permissions.

| Parameter        | Type                | Description                                             |
| :--------------- | :------------------ | :------------------------------------------------------ |
| `query`          | `string` (required) | A complete GraphQL query or mutation document           |
| `variables`      | `object`            | Values for the document's variables                     |
| `operation_name` | `string`            | The operation to run when the document contains several |

<Callout type="warning" title="Mutations are real">
  `graphql_execute` can run mutations that create, modify, or delete data in your account. Assistants confirm before
  destructive operations, but review what your assistant proposes to run — especially anything `operations_list` flags
  as `destructive`, `billing`, or `admin`.
</Callout>

Every execution is guarded: queries are capped at depth 10, responses at 1 MB, and upstream calls at 30 seconds. Subscriptions are rejected — this transport doesn't support them.

## Recommended Workflow

Use the tools in sequence:

```text
operations_list  →  schema_search  →  schema_details  →  graphql_execute
   (survey)          (narrow down)      (get it exact)       (run it)
```

Most MCP clients let the assistant drive this on its own — you ask in plain language, and it works through the chain.

## Example Prompts

> List the projects in my LottieFiles workspace and how many animations each contains.

> Find the GraphQL operations related to file uploads and explain what each one needs.

> Draft — but don't run — a mutation that renames animation X to "hero-loader-v2".

> Which operations in the schema are classified as destructive?

> Fetch the details of my most recently modified animation, including its download URL.

## Resources and Prompts

Beyond tools, the server publishes MCP resources and prompts that capable clients can use directly.

**Resources**

| URI                                      | Description                                                 |
| :--------------------------------------- | :---------------------------------------------------------- |
| `lottiefiles-schema://summary`           | Counts and a high-level inventory of the schema             |
| `lottiefiles-schema://categories`        | The operation category names that `operations_list` accepts |
| `lottiefiles-docs://tool-workflow`       | The recommended tool workflow as Markdown                   |
| `lottiefiles-schema://operations/{kind}` | Operations of one kind (template)                           |
| `lottiefiles-schema://types/{name}`      | One type by name (template)                                 |

**Prompts**

| Prompt                    | Arguments                | Use it to                           |
| :------------------------ | :----------------------- | :---------------------------------- |
| `discover_operation`      | `goal`                   | Find the right operation for a goal |
| `draft_graphql_query`     | `goal`, `operation_name` | Draft a correct query for a goal    |
| `review_graphql_mutation` | `mutation`               | Review a mutation before running it |
| `inventory_workspace`     | `workspace_id`           | Summarize a workspace's contents    |

The server also autocompletes operation names, type names, and categories through the standard `completion/complete` method.

## Rate Limits

You can send up to **60 requests per second**. Beyond that, the server responds with `429` and a `Retry-After` header; well-behaved clients retry automatically. Typical schema exploration stays well under this limit.