# Lolly for agents

Lolly turns a URL into a finished, on-brand file. A tool is a manifest, a template and
optional hooks - data, not code - and every input a tool takes is a query parameter.
Build the URL and you have built the asset: the same parameters render the same file in
the browser, on the desktop, in the terminal and over MCP. Engine 1.184.0.

This page is the short version for a machine reader. The full docs live at https://lolly.tools/info/
and every page there has a markdown twin at the same path with `.md` in place of `.html`.

## Entry points

| What | Where |
|---|---|
| This page | https://lolly.tools/agents.md |
| Docs index (llms.txt) | https://lolly.tools/llms.txt |
| Every docs page in one file | https://lolly.tools/llms-full.txt |
| Discovery record (JSON) | https://lolly.tools/.well-known/lolly.json |
| HTTP surface (OpenAPI 3.1) | https://lolly.tools/openapi.json |
| Format claims | https://lolly.tools/info/capabilities.json |
| Tool catalog (generated index) | https://lolly.tools/catalog/tools/index.json |
| One tool's manifest | https://lolly.tools/tools/{id}/tool.json |
| Sitemap | https://lolly.tools/info/sitemap.xml |

Fetch the catalog index once to learn the tool ids, then a manifest for the inputs.
Do not guess parameter names.

## A URL is the API

```
https://lolly.tools/#/tool/{id}?{input}={value}&{input}={value}&format={ext}&export
```

- Every key that is not reserved is a tool input, named by its manifest `id` (or its
  shorter `urlKey`).
- Reserved keys control output: `format`, `export`, `copy`, `width`, `w`, `height`, `h`, `unit`, `dpi`, `profile`, `bleed`, `marks`, `password`, `filename`, `output`, `_v`, `slot`, `full`, `lang`, `z`.
  `export` and `copy` are presence flags (download or copy on load), `_v` pins the
  tool version and `z` is a packed query. The complete set with meanings:
  https://lolly.tools/info/build/url-mode.md
- Unknown keys are ignored and bad values fall back to defaults, so validate against the
  manifest before you emit a link.

## Getting bytes

1. **Hot-link render, no auth.** `GET https://lolly.tools/tool/{id}.{ext}?{inputs}` answers with the
   file for the browser-free formats - `svg`, `emf`, `eps`, `eps-cmyk`, `dxf`, `exr`, `hdr`, `penpot`, `html`, `md`, `txt`, `json`, `csv`, `ics`, `vcf` - plus `png` for SVG-native tools.
   Tools with status `official` or `community` only; Content Credentials are off so the
   bytes are cacheable (a strong ETag, a day at the CDN); renders are rate-limited per
   address. The route is per deployment: switched off on lolly.tools, live on
   https://lolly.art. A `404` means the tool is not public there or the route is off; a
   `400` names the reason (a browser-tier format, an output bound, a query over 4096
   characters). Full contract: https://lolly.tools/openapi.json
2. **MCP.** `https://mcp.lolly.tools/mcp` renders every format a tool declares (a headless browser sits
   behind it); `https://lolly.tools/api/mcp` is the browser-free tier with the same tools. Both take
   the same bearer token, or an OAuth 2.1 flow with dynamic client registration -
   discovery at `https://lolly.tools/.well-known/oauth-authorization-server`. Tools:
   `lolly_compile`, `lolly_inspect`, `lolly_measure`, `lolly_validate`, `lolly_diff`, `lolly_package`, `lolly_list_tools`, `lolly_describe_tool`, `lolly_build_url`, `lolly_render`, `lolly_transform`, `lolly_redact`, `lolly_verify`. Resources:
   `lolly://catalog`, `lolly://assets`, `lolly://tokens`, `lolly://tool/{id}`, `lolly://tool/{id}/preview`, `lolly://asset/{id}`. The intended flow is list, describe,
   render, and verify when you need to prove a file is an untouched export.
3. **CLI.** `lolly {id} --{input}={value} --export={ext} --output={file}` is the same
   parameter table with `--` in front; in a source checkout, `npm run cli -- {id} ...`.
   Vector and data formats need nothing installed. Raster, PDF and video run in a scoped
   headless browser (`lolly install-browser`), one render path with the app.

## Rules that save a round trip

- Read the manifest. Formats are per tool; only request one the tool declares.
- Asset inputs take catalog ids. Read `lolly://assets` (or the catalog index) first and
  never invent an id.
- Pin `_v` in automation so a tool update cannot change your output.
- Byte-stable: `svg`, `emf`, `eps`, `eps-cmyk`, `dxf`, `md`, `txt`, `json`, `csv`, `vcf` and
  `png` from an SVG-native tool. Not byte-stable: `pdf` (creation dates), `ics` (a
  required DTSTAMP), `penpot` (the archive records its creation time), everything the browser tier paints (`jpg`, `webp`, HTML-layout
  `png`, `gif`, `apng`, `webm`, `mp4`) and anything carrying a Content Credential,
  which is signed with a fresh timestamp each time.
- Exports from the app and from `lolly_render` carry Content Credentials (C2PA) by
  default; the hot-link route never does. `lolly_verify` and `lolly validate --json`
  read them back with one shared verdict vocabulary.
- Tools with status `experimental` watermark their exports.
- A link's inputs are public by construction. Put no secrets in one.
- Uploads never travel in a URL. Device-local files are for the app, `lolly_transform`
  and the CLI.

## Read next

- Driving Lolly from an agent: https://lolly.tools/info/build/ai-agents.md
- The MCP server: https://lolly.tools/info/build/mcp.md
- URL mode, the whole parameter table: https://lolly.tools/info/build/url-mode.md
- The CLI: https://lolly.tools/info/build/cli.md
- Formats, one page each: https://lolly.tools/info/formats/
- Author a tool: https://lolly.tools/info/build/authoring-tools.md
- Source: https://github.com/lolly-tools/lolly (MPL-2.0)