Instructions Tool

The Instructions Tool lets you attach your own operating guidance to a Gateway or Deployment, so any agent connecting to it gets the context a plain tool definition can’t provide. It’s written by you and your team, covering things like your naming conventions, which environment or data source to use for a given task, or the sequence tools should be called in. With the Instructions Tool configured, a Gateway or Deployment stops being a generic set of tools and becomes one that’s tailored to how your organization actually works. Tool definitions tell an agent what it can call. The Instructions Tool tells it how to actually use those tools well.

​

Why It Matters

Tool schemas describe parameters and return types, but they rarely capture the operational knowledge a human on your team would take for granted. Consider a user who’s spent the last twenty messages debugging a CSV export failure in Claude Code. The LLM already knows the affected customer, the environment, the steps to reproduce, and a pipeline_ID pulled from the logs because it is sitting in the LLM’s context window. That’s everything their team needs in a Jira ticket. The user should just be able to say, “file a bug for this.” In an off the shelf Jira MCP, the create_ticket() tool schema only tells the LLM how to create an issue with a project, type, summary, description, assignee, and labels. It has no way to know in which of the dozen boards to file the bug report, which team member owns that part of the product, or that customer-reported bugs need the “customer escalation” label. The LLM has both too much information (not everything in the conversation history needs to go in the ticket) but also too little information. Jira conventions can vary between teams, let alone organizations. By default, your LLM doesn’t know yours. Without any guidance, the agent is likely to create a generic, unstyled ticket on the wrong board, missing half the fields your team relies on while providing information that the bug ticket doesn’t need. It knows the specific issue and how Jira tickets work on a high level, but it has an important gap vis-a-vis the specific org and team. With the Instructions Tool configured, the agent already has all three parts of what it needs: the substance from the conversation, the capability to create a Jira ticket, and your team’s conventions for filing one. It picks the right board, assigns the issue to whoever owns that competency, and includes all the information your team needs without flooding the description with information they don’t. 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 with instructions configured, it sees an extra tool alongside your normal tools, named get_tool_instructions. That tool takes no parameters. When the agent calls it, it gets back the Markdown content you wrote. The tool’s description, by default, tells the agent to call it before any other tool in the Gateway or Deployment, meaning your agent always has the context it needs before it can take action. Because this only costs context when the agent actually decides to use that Gateway or Deployment, you get the benefit of detailed, tailored guidance without permanently bloating every conversation’s context window with information that isn’t always relevant.

​

Configuring Gateway Instructions

1. Open the Gateway you want to configure in the Gateway editor.
2. Select Gateway Instructions from the list of connected apps in the sidebar. It’s always pinned at the top of the list.
3. Fill in the two fields:

4. Save the Gateway.

Once Instructions has any content, a Configured badge appears next to Gateway Instructions in the sidebar, and the get_tool_instructions tool becomes available to every session connecting to that Gateway. To remove it, click Clear Instructions and save; this empties both fields and removes the tool.

​

Configuring a Deployment Instruction Tool

1. Open the Deployment you want to configure and go to the Available Tools step.
2. Toggle {your-deployment-name}__get_tool_instructions. This is the first row in the tool list, above your Deployment’s actual tools and is defaulted to off.
3. Click Edit to open the instructions dialog, and fill in the same two fields described above (Tool Description and Tool Instructions), with the same character limits.
4. Save your changes, then save the Deployment.

​

Writing Good Instructions

The agent pulls your instructions directly into its working context, so the same guidelines that make for a good internal wiki page apply here, with an even stronger bias toward brevity:

• Be specific and concrete. “File export issues on the Data Pipeline board and assign Highest priority when a customer is affected” is far more useful than “use the correct board and priority.”
• Lead with what’s most likely to trip 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 provide the needed information.
• Keep it scannable. Short sections, bullet points, and a handful of concrete examples work better than long prose. Remember the agent is reading this into its context window, not browsing a document.
• Update it as things change. If a convention changes on your end (a new board, a renamed field), update the instructions the same way you’d update any other piece of documentation your team relies on.