What Is Prompt Engineering?

Prompt engineering is not finding a clever sentence for a model. It is defining the instructions, tool interfaces, examples, and output contracts that shape an agent's behavior, then keeping those artifacts reviewable as the system changes.

Why prompt engineering matters

A model does not know your business. It works from the instructions and context it receives. Reliable behavior usually comes from a few unglamorous decisions made consistently:

The practices that matter are pretty consistent across the industry:

• A stable system prompt. This is the base instruction set sent before the user message. It should not change because the clock moved or a per-request value changed. A stable prefix can also be cached by the model provider.
• Tool descriptions written as an interface, not as documentation. If a model can call a tool, then the sentence describing that tool is part of the prompt. That sentence tells the model when to call it, what to expect, and whether it is a valid next step.
• Few-shot examples. A couple of representative examples often communicate a boundary better than another paragraph of abstract instructions.
• Structured formatting. Clear sections for role, constraints, and output format are easier to follow than one long paragraph full of nuance.

Anthropic's prompt caching documentation makes the same point: put the cache breakpoint after the stable prefix. If a timestamp or other per-request detail appears before it, the cache breaks. The engineering question is whether each team has to remember that rule manually.

How Matimo engineers this

Production agents fail across several surfaces: what the model is told, what it sees, what it can touch, how it reasons, and how its steps compose. This is the first post in a five-part series on how Matimo treats those surfaces as platform properties rather than ad hoc configuration.

We laid out that framing in Introducing Matimo.ai, and the rest of the series follows the same pattern. This post is about prompt engineering specifically: how Matimo turns the general practice above into something inspectable and versionable instead of a text box hidden inside one teammate's brain.

What prompt engineering looks like in production

In many teams, prompt engineering is one person and a text box. Someone who knows the model's quirks writes a system prompt, tests a few cases, and ships it. That works until the owner leaves, the model changes, or a reviewer asks which exact instruction produced a decision.

The problem is not the prompt engineer. It is the missing structure around the work: no durable version history, no safe separation between tone and behavior, and no exact artifact to inspect when an agent behaves unexpectedly. Matimo addresses that at two levels: Workbench exposes the configuration, while OSS keeps tool definitions consistent and prevents sensitive parameters from reaching the model.

What you control: Matimo Workbench's Agent Builder

Matimo Workbench's Agent Builder exposes prompt engineering as named controls rather than a blank system-prompt field:

• Personality and communication style. Creativity level, tone, and decision style are settings, not something you have to express in a paragraph and hope the model interprets correctly.
• Eight built-in role templates. Sales Representative, Customer Support, Data Analyst, Research Assistant, Content Creator, Data Processor, Operations Assistant, and General Assistant. These are starting configurations for common jobs, not a blank page that nobody wants to edit from scratch.
• KB (Knowledge Base) Grounding. For sensitive domains like medical, legal, financial, or compliance work, grounding requires the agent to cite an approved source before answering instead of trusting its memory.

The useful property is inspectability. An admin can review personality settings and grounding rules without reverse-engineering a wall of prose. That does not guarantee perfect behavior, but it makes the intended behavior visible and reviewable.

One prompt artifact, not five copies of it

Tool descriptions are another place where systems drift. A tool gets described for the internal runtime, then described again for LangChain, MCP, and whatever else consumes it. Each copy can quietly teach the model something different.

Matimo OSS uses one YAML file, definition.yaml, with a single description field. That field flows unmodified into the LangChain, MCP, and CrewAI integrations. The model gets the same description regardless of which integration is calling the tool.

That matters because a tool description is part of the prompt. Five slightly different descriptions make one implementation look like five different tools to the model.

A real failure case is useful here. We saw a support agent start creating tickets for every customer follow-up because the tool description was written a little too broadly: "create a ticket for a customer issue." The model interpreted that as a valid action for almost any inbound message. The fix was not a model magic trick. It was tightening the description so the tool only applied to actionable customer problems, and not routine conversations. That is prompt engineering in the real world: a few words change behavior.

Secrets never reach the model

A tool's parameters are also part of the model's prompt. Matimo strips credential-shaped parameters automatically. isSecretParameter() catches common forms including snake_case such as api_token and API_KEY, underscore-bounded names such as _token_, and camelCase names such as getToken and apiKey.

Matching parameters are excluded from the schema before it reaches the model. The value is injected server-side after the model chooses the tool. The model can request a Slack message without seeing the token that sends it.

The system prompt is designed to stay boring

Matimo Workbench's reasoning engines build system prompts through a shared method, buildSystemPrompt(), and that method follows published guidance. Anthropic recommends keeping the cacheable prefix stable and moving per-request details into the user turn. We do that on purpose.

Two examples:

• The current date used to be baked into the system prompt. It now lives in the user turn instead, so the system prompt remains byte-stable and is eligible for provider-side prompt caching.
• Tool-specific guidance loads conditionally. Browser and Playwright instructions are only added when the agent actually has those tools assigned. If it does not, that block is not in the prompt at all.

This is not glamorous. It keeps the prompt cacheable and makes changes easier to review.

What we did not build, on purpose

We do not have an automated prompt optimizer that rewrites tool descriptions or system prompts behind the scenes. The text in definition.yaml and the Agent Builder configuration are the prompt. A human writes them, and they stay unchanged until another human edits them.

That is a deliberate tradeoff. A silent optimizer would also silently rewrite the artifact an auditor is meant to trust. A reviewer should be able to open the YAML and see what shipped, rather than infer it from a hidden optimization loop.

Frequently asked questions

What is prompt engineering?

Prompt engineering is the practice of structuring the system prompt, tool descriptions, examples, and output constraints so a model behaves more reliably. In production, those instructions should be reviewable artifacts rather than one-off text.

How is prompt engineering different from context engineering?

Prompt engineering is about the instructions and tool descriptions the model gets before it reasons. Context engineering is about everything else that ends up in the model's context window during a task: retrieved documents, memory, and conversation history. Matimo treats them as separate layers.

Why does a stable system prompt matter?

A system prompt that changes on every call cannot be cached effectively and is harder to review. Keep the stable prefix unchanged and move per-call details into the user turn.

Does Matimo have a dedicated prompt-optimization tool?

No. Matimo does not auto-tune tool descriptions or system prompts behind the scenes. Human-authored configuration remains the source of truth.

How does Matimo keep credentials out of a model's tool descriptions?

Matimo checks parameter names against common secret patterns such as api_token, API_KEY, and apiKey, then strips matches from the schema before the model sees it. The secret is injected server-side after the model chooses the tool.

What is Agent Builder's role in prompt engineering?

Agent Builder is the configuration layer. It provides named controls for personality, role templates, and grounding, making intended behavior inspectable without requiring every change to be expressed as free-form prose.

Prompt engineering is one of five surfaces where production agents break. The rest of this series covers what the agent sees, what it can touch, how it reasons, and how steps compose in Graph Engineering: How Matimo Studio Is Built for It.

To inspect the configuration layer, use Matimo Workbench, which includes Agent Builder, role templates, and KB Grounding. To work with the YAML layer directly, install Matimo OSS: npm install matimo or pip install matimo.