--- title: "The catalog" description: "See which agents, tools and skills a tenant has, and which nodes are ready to run them." canonical_url: "https://docs.oz0.ai/build/plugins/catalog" --- # The catalog > See which agents, tools and skills a tenant has, and which nodes are ready to run them. For: tenant administrators and plugin authors. Use the catalog to find the agents, tools, skills, flows and plugins installed for a tenant, and the nodes ready to run them. The catalog also shows the tool policy that applies to each listed function. ```bash [Terminal] oz0 catalog oz0 catalog --tenant acme --json ``` The catalog lists, for one tenant: - Agents, with their task queue, the pool they share with the plugin's other agents that need the same labels, and the nodes ready to run them: nodes that run the agent's plugin and have the labels it requires. - Tools, as `.`, and the nodes that have started them; and for each function, its annotations and what the tenant's [tool policy](https://docs.oz0.ai/govern/tool-policy) does with its calls: allow, approve or refuse, and why. - Skills, with their descriptions. - Flows, with their steps and the task queue, their plugin's pool: `pool.`, or with [shared pools](https://docs.oz0.ai/concepts/routing#shared-pools) the pool of the plugin's node selector, `pool.~`. - Plugins, with where each comes from (`git`, `workspace`, `bundle` or `oci`) and what its version is locked to: a commit, or the SHA-256 digest of a [bundle or OCI artifact](https://docs.oz0.ai/build/plugins/sources). The console's Agents and Tools pages show the same under each plugin's name. ## Pages and search A tenant may have thousands of agents ([limits](https://docs.oz0.ai/concepts/limits-and-scaling)), so the catalog comes from the server a page at a time, as the other lists that grow do ([lists and pages](https://docs.oz0.ai/reference/list-pages)): 25 agents and flows unless `page_size` asks for more, at most 100, each by name, with the tenant's tools and skills whole on the first page (unless `--kind` asks for one kind, which is then paged too). `oz0 catalog` reads every page. The search runs on the server: ```bash [Terminal] oz0 catalog --query invoice --kind agent oz0 catalog --plugin billing --kind tool --json ``` `--query` keeps entries whose name, or a word of whose name or description, starts with each of its words: `inv ref` finds "Answers invoices and refunds", `voices` does not. `--plugin` and `--kind` (`agent`, `flow`, `tool` or `skill`) narrow it further. With `--json` the answer has `totalSize`, how many entries matched. The admin API's `GetCatalog` and the runtime API's take `page_size`, `page_token`, `query`, `plugin` and `kind`, and answer `next_page_token` and `total_size`. To look one entry up, send its exact `name` instead of a `query`: a query for `summarize` also finds every `doc-summarize-…` agent, and a page of those may not hold the one you want. A page token is valid only for the tenant and the search it was made for: ask for the first page again after changing either. The runtime API's catalog has the whole catalog's `hash` on every page. ## What tool definitions cost Every model request of an agent carries the definitions of all the tools it may use: the name the model sees (`__`), the description and the input schema. An agent with forty functions can spend thousands of tokens on them in every request before it says anything. The catalog shows an estimate of it: per function (`tokens` in `--json`, and on the console's Tools page) and per agent, all its tools together (the `TOOL TOKENS` column, `toolTokens` in `--json`, and the agent's [capability card](https://docs.oz0.ai/govern/inventory#the-capability-card)). The figures come from the tools' listings as the first node recorded them, so a function no node has listed yet is named and left out, never guessed. They are estimates: the engine counts the text as a byte-pair tokenizer of the cl100k family would, without downloading one, and is within a few percent of such a tokenizer on our own plugins (3% on average, 14% at worst for one function). Each provider tokenizes differently and adds a tool prompt of its own, so use the numbers to compare tools and agents with each other, not to bill. Before a plugin is installed, `plugin inspect` and `plugin lint` show the same estimate from its [measured listing](https://docs.oz0.ai/build/parts/tools/snapshots#the-measured-listing), and `plugin lint` fails when an agent's tools pass its [size budget](https://docs.oz0.ai/build/parts/tools/definitions#the-size-budget) (8,000 tokens unless it sets one). For an agent that [loads its tools lazily](https://docs.oz0.ai/build/parts/agents#lazy-tool-loading), the per-agent figure is what its requests carry, the two discovery tools and its built-ins; its card also shows what every function it lists would add. Use it to check that an agent has somewhere to run before you start jobs for it. A job for an agent no node can run waits in its queue until one can. An agent's name belongs to one plugin per tenant, so a job for it always means one definition. So does a tool's ID, so `.` always means one plugin's server. A tool ID that two plugins provide, from before installs refused that, shows on both rows as a clash: no node runs it until one of the plugins goes. ## Sitemap See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.