<) and is installed only if it passes. Once installed, the gem's page lists what it can do.
- **It can reach nothing by default**: anything that needs user configuration (accounts, mailboxes, knowledge) stays off until the user turns it on (see [Permission Model](/en/dev/permissions.md)).
- **Isolation**: each gem has its own data folder and its own process. Other gems cannot read them.
- **Use**: the user asks the AI to use it in chat, or its own SOPs run automatically according to their triggers (see [Events and Triggers](/en/dev/events.md)).
## How the AI uses your gem
In chat the user talks to the Chat agent. By default it has two tools: `read_skill` and `tool_search`. The user can remove them in "Settings › AI Settings › Agent", or add them to other agents.
- **The AI knows which gems the user has installed and what each one offers.** For an agent that has `read_skill`, the system prompt lists every installed gem, one line each: name, id, and the `description` from the manifest (see [Manifest Reference](/en/dev/manifest.md#descriptions) for how to write it). Below it, each exposed item (a tool, SOP, or agent marked `expose: true`) gets one line with its description; SOPs are marked (SOP) and agents are marked (agent). If a gem exposes no tools, the AI does not know they exist.
- **To use a gem, read its id with `read_skill`.** The result contains its skill (the full text of `skill/SKILL.md` and the name of each file under `skill/references/`) and the items the gem exposes. From the next step on, those items are in the AI's tool list until the conversation ends. A gem without a skill is opened the same way; the result just has no skill in it.
- **An exposed agent is a tool.** The AI calls `gem.<id>.<agent name>({ task })` and hands it the task in a paragraph. The agent finishes the task in its own session, with the tools it declares and the model the user chose for it, and its last reply is the tool's result. It sees only this task. For how to decide between exposing a tool or an agent, see [Manifest Reference](/en/dev/manifest.md#exposing-items-expose).
- **Reference material is read on demand.** The AI uses `read_skill` with a name listed in the result (`<gem id>/skill/references/…`) to read a file. The gem's tools appear at the same time. For how to write it, see [Manifest Reference](/en/dev/manifest.md#skill).
- **It can also search by keyword.** `tool_search` searches installed gems (names, descriptions, and the names and descriptions of exposed items) and Notochord's built-in tools. What it finds (up to 5 items) also appears in the tool list.
- **Reading and searching never ask the user.** They only let the AI see what a gem offers; having seen it, the AI may still not use it.
- **The first call asks once.** The first time the AI calls an item the gem exposes, the app shows a dialog asking the user to agree. The question is about the whole gem; once the user agrees, calling any exposed item in this conversation no longer asks. The consent applies only to this conversation; a new conversation asks again. If the user refuses, the call is not executed and the AI receives a refused result.
- **Exposed items appear only as a whole gem**; you cannot get just one of them. To the AI, a SOP is a tool, except that it may need to wait (for approval or for a schedule), in which case it first returns a run id.
- **A tool that is not exposed can be called only by the gem itself**: its SOPs, agents, and pages. If another session calls it, the call is refused whether or not it is in the tool list, and the user is not asked.
- **Which gems appear in the gem list**: gems that expose at least one item, and gems that **expose nothing but have a skill** (a `skill/SKILL.md`). Reading the latter gives only text and nothing that needs the user's consent. A gem that exposes nothing and has no skill does not appear (it works only through its own pages and scheduled SOPs). A gem's own agents are not affected by any of this: which tools they can use is determined by the header of their file (see [Manifest Reference](/en/dev/manifest.md#agents)), and they do not see this gem list.
]]>