> ## Documentation Index
> Fetch the complete documentation index at: https://graph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# The tool catalog

> One namespace for MCP, user, plan, and built-in tools

Every capability in graph is a tool in a single catalog, visible to the agent, the planner, and plan steps alike. Namespacing tells you where each tool comes from:

| Name                   | Source                                                               |
| ---------------------- | -------------------------------------------------------------------- |
| `linear__list_issues`  | the `[mcp.linear]` server — [MCP servers](/tools/mcp-servers)        |
| `user__git_log`        | a YAML file in `[tools].paths` — [user-defined](/tools/user-defined) |
| `builtin__infer`       | a bundled [tool pack](/tools/builtins) compiled into the binary      |
| `plan__project_status` | a plan document — [plans](/plans/overview)                           |
| `plan_and_execute`     | reserved: [on-the-fly planning](/plans/the-planner)                  |

A plan step's `tool_name` may also be one of the seven **control steps** — [`exit`](/plans/exit-gates), [`ask`](/plans/ask-step), [`agent`](/plans/agent-step), [`decide`](/plans/branching), [`filter`](/plans/selection), and [`map`/`reduce`](/plans/iteration). They are bare names with no namespace, and they are not tools: the executor evaluates them, so they belong to no registry and cannot be invoked. They are listed and described alongside the catalog anyway, under the `(control)` source, because writing a step needs their input schemas exactly as much as a tool's.

## Inspecting and invoking

```bash theme={null}
graph tools list                     # the whole catalog, grouped by source (--json for a script)
graph tools show linear__list_issues # description + input/output schemas (--json for a script)
graph tools test user__git_log '{"repo":"/path","count":3}'   # direct invocation
```

`tools test` uses the same [input model](/plans/inputs) as plans (`'{json}'`, `@file`, `-`, `--input k=v`) and is the fastest way to learn a tool's real output shape before referencing it in a plan.

`tools list` and `tools show` answer for the whole step vocabulary, control steps included (`graph tools show ask`). `tools test` does not — a control step has no implementation to call, and asking for one is refused with an explanation rather than an "unknown tool".

## Composition rules

* **Plan steps can call anything in the catalog** — MCP tools, user tools, **other plans** (`plan__*`), and even `plan_and_execute`. Plans are composable by design: build small focused plans and orchestrate them from larger ones.
* **Cycles are caught, depth is bounded.** The pipeline tracks the plan call stack — `a → b → a` fails immediately with the cycle named, and nesting is capped at 8 levels.
* **Everything feeds the [shape cache](/tools/shape-cache)** — every successful call from any surface records the tool's observed output shape.

## Keeping the catalog sharp

The agent and the planner reason over every tool description in the catalog, so curation improves both cost and routing: allowlist or blocklist per-server tools with `include_tools`/`exclude_tools`, and patch weak descriptions or missing output schemas with `tool_overrides` — see [filtering and overrides](/tools/mcp-servers#filtering-and-overrides).


## Related topics

- [Scripting contract](/reference/scripting-contract.md)
- [Core concepts](/getting-started/concepts.md)
- [Plan workbench](/workbench/plan-workbench.md)
- [CLI reference](/reference/cli.md)
- [Introduction](/getting-started/introduction.md)