Instructions Tool

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

To remove the tool, click Clear Instructions and save. This empties both fields and removes get_tool_instructions from the Gateway.

​

Configure Deployment instructions

​

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

​

Related Resources