> ## Documentation Index > Fetch the complete documentation index at: https://explore.airia.com/llms.txt > Use this file to discover all available pages before exploring further. # Instructions Tool > Attach your team's operating guidance to a Gateway or Deployment so any connecting agent uses your tools the way your organization actually works. The Instructions Tool attaches operating guidance you write to a Gateway or Deployment. Any agent that connects then gets context a plain tool definition can't provide: your naming conventions, which environment or data source to use for a given task, or the order tools should be called in. Tool definitions tell an agent *what* it can call. The Instructions Tool tells it *how to use those tools well*. With it configured, a Gateway or Deployment stops being a generic set of tools and becomes one tailored to how your team works. The Instructions Tool does not grant new permissions and does not add or change tools. It only supplies guidance text. Every tool call still runs through your normal policy, credentials, and monitoring. ## Why teams use it Tool schemas describe parameters and return types, but they rarely capture the operational knowledge a teammate takes for granted. Without that context, an agent knows *how* a tool works in general but not how your org uses it. Consider a user who has spent twenty messages debugging a CSV export failure in Claude Code. The model already has the affected customer, the environment, the reproduction steps, and a `pipeline_ID` from the logs in its context window. That's everything a Jira ticket needs. The user should be able to say "file a bug for this." In an off-the-shelf Jira MCP, the `create_ticket()` schema only describes how to create an issue: project, type, summary, description, assignee, labels. It can't know which of a dozen boards the bug belongs on, who owns that part of the product, or that customer-reported bugs need the `customer escalation` label. Jira conventions vary between teams, let alone organizations, and by default the model doesn't know yours. So it files a generic ticket on the wrong board, missing the fields your team relies on while padding the description with detail the ticket doesn't need. With the Instructions Tool configured, the agent has all three parts it needs: * The substance from the conversation * The capability to create a Jira ticket * Your team's conventions for filing one It picks the right board, assigns the issue to whoever owns that area, and includes only what your team needs. The user's one line, "file a bug for this," produces a ticket indistinguishable from one a trained teammate would file. ## How it works When an agent connects to a Gateway or Deployment that has instructions configured, it sees an extra tool alongside your normal tools, named `get_tool_instructions`. The tool takes no parameters. When the agent calls it, it gets back the Markdown content you wrote. By default, the tool's description tells the agent to call it before any other tool in the Gateway or Deployment, so the agent always has your context before it acts. The instructions only cost context when the agent actually decides to use that Gateway or Deployment. You get detailed, tailored guidance without permanently bloating every conversation with information that isn't always relevant. ## Configure Gateway instructions Open the Gateway in the Gateway editor, then select **Gateway Instructions** from the list of connected apps in the sidebar. It's always pinned at the top of the list. Enter a **Tool Description** and your **Instructions**. See the field reference below. Once **Instructions** has any content, a **Configured** badge appears next to **Gateway Instructions**, and `get_tool_instructions` becomes available to every session connecting to that Gateway. | Field | Required | Limit | Description | | -------------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tool Description** | No | 500 characters | What the agent reads in its tool list to decide when to call `get_tool_instructions`. Leave it blank to use the recommended default, which tells the agent to call it first. | | **Instructions** | Yes | 8,192 characters | The Markdown content returned to the agent when it calls the tool. This is where your actual guidance goes. | To remove the tool, click **Clear Instructions** and save. This empties both fields and removes `get_tool_instructions` from the Gateway. If you leave **Instructions** blank, no instruction tool is added to the Gateway and the agent never sees this surface. There's no cost to leaving it unconfigured. ## Configure Deployment instructions Open the Deployment you want to configure and go to the **Available Tools** step. Turn on **\{your-deployment-name}\_\_get\_tool\_instructions**. It's the first row in the tool list, above your Deployment's actual tools, and is off by default. Click **Edit** to open the instructions dialog, then fill in the same two fields as a Gateway (**Tool Description** and **Tool Instructions**), with the same character limits. Save the dialog, then save the Deployment. ## Writing good instructions The agent pulls your instructions directly into its working context, so the guidelines for a good internal wiki page apply, with an even stronger bias toward brevity. * **Be specific and concrete.** "File export issues on the `Data Pipeline` board and set `Highest` priority when a customer is affected" beats "use the correct board and priority." * **Lead with what trips an agent up.** Naming mismatches and required fields that aren't obvious from the schema. * **Use it to replace `list_...` tools.** List tools tend to be token-inefficient and often don't return what the agent needs anyway. * **Keep it scannable.** Short sections, bullet points, and a few concrete examples beat long prose. The agent reads this into its context window, not a browser. * **Update it as things change.** When a convention changes on your end (a new board, a renamed field), update the instructions the way you'd update any other doc your team relies on. ## Troubleshooting **Cause:** On a Gateway, the **Instructions** field is empty, so no tool is added. On a Deployment, the **\{your-deployment-name}\_\_get\_tool\_instructions** toggle is off. **Fix:** Add content to **Instructions** (Gateway) or toggle the tool on (Deployment), then save. **Cause:** A custom **Tool Description** that doesn't tell the agent to read instructions first. **Fix:** Leave **Tool Description** blank to use the recommended default, which instructs the agent to call `get_tool_instructions` before any other tool. ## Related Resources Change apps, credentials, and tools after you create one Build a Gateway or Deployment step by step Decide which one fits before you build Keep large Gateways context-efficient