Seven best practices for writing high quality prompts

Getting useful output from an agent comes down to how you ask.  Prompt engineering is an evolving space, especially as an agent continuously learns and improves. Too vague a prompt will give you a vague result. A specific, context-rich prompt gets a collection you can actually ship, but may imply you know exactly what you want the system to do.

I’ve spent the past few months using Postman Agent Mode daily. I’ve built hundreds of collections from scratch, debugged countless flaky tests, generated documentation, wired up CI/CD pipelines, and generated entire React apps based on APIs in Postman. Along the way, I’ve figured out what makes the difference between a prompt that saves you 3 hours and one that wastes 20 minutes going in circles.

Here are 7 prompting practices for Agent Mode that consistently get me better results today. One of the huge benefits of launching an agent is that it is continuously learning and improving. You can consider these best practices as a living document. What works now will likely evolve as the Agent Mode learns.

1. Be specific about what you want built

Specificity is the single highest-leverage change you can make to any prompt. Research from Anthropic, OpenAI, and the broader prompt engineering community consistently points to one root cause behind weak AI output: vague instructions. When a prompt describes a category of work instead of the actual deliverable, the model fills in the blanks — and rarely in the way you intended.

Think of Agent Mode like a highly capable new team member. They have deep technical knowledge but no institutional context. The more precisely you describe what you want — the name, the format, the constraints, the expected outcome — the better the result. Anthropic’s own guidance puts it bluntly: “Be specific about the desired output format and constraints.”

Whenever writing a prompt, I always try to keep these three things in mind:

Describe the output, not the task.

Instead of “create an API collection,” specify the collection name, the source material (an OpenAPI spec, an existing request, a folder), and any structural requirements like variables or folder organization.

Use positive framing

Prompt engineering research consistently shows that telling a model what to do outperforms telling it what not to do. “Set the base_url as a collection variable” is more actionable than “don’t hardcode the URL.”

Include success criteria

A good prompt answers the question: how would you know the output is correct? Adding a constraint like “validate that all requests return a 200 status code” gives Agent Mode a built-in quality bar to work toward.

Here is an example of what this might look like:

Vague prompt:

“Create an API collection for user management”

Specific prompt:

Create a collection called ‘User Management API’ based on this OpenAPI spec. Set the base_url as a collection variable. Organize requests into folders by resource type (users, roles, permissions) and add a pre-request script that injects the auth token from the environment.

 

The specific prompt gives Agent Mode a name, a source, a structure, and a behavior — four dimensions the vague version leaves entirely open. That’s the difference between a scaffold you have to rebuild and a collection you can start testing immediately. You don’t need to know how to implement it, Agent Mode knows that already, but it does need specific guidance on what you want to build.

2. Give Agent Mode context with the @ symbol

This is the feature that separates a good prompt from a great one. When you type @ in the Agent Mode chat, you can attach existing collections, folders, requests, environments, or API specifications as reference material. Agent Mode uses this context to understand your API structure, naming patterns, and conventions.

For example:

Review @my-collection and add comprehensive test scripts for every request. Validate status codes, response time under 500ms, and check that all responses match the expected JSON schema.

 

I’ve found that dragging in an existing collection before asking Agent Mode to generate tests produces dramatically better results than describing the API from memory. The agent can read your request structure, existing variables, and response examples — then write tests that actually match your API.

3. Chain prompts for multi-step workflows

Agent Mode remembers your conversation. Use that. Instead of cramming everything into one massive prompt, build up in steps. Each prompt builds on what Agent Mode produced in the previous turn. But also, don’t be afraid to open a new Agent Mode tab to start a new conversation. Just like humans, too much information can muddy up our thinking. Sometimes, it’s good to step back, take a break and start on a new topic fresh.

Here is an example of a conversation you might have in Agent Mode.

Step 1: Create the foundation

Create a collection called Payment Processing API based on the routes in this react project. Set the base_url as a collection variable.

Step 2: Add tests

Add test scripts to each request in the Payment Processing API collection. For the create payment request, validate a 201 status code, save the payment_id to a collection variable, and check the response includes amount, currency, and status fields. For get payment, validate a 200 and that the payment_id matches. For refund, validate a 200 and that the status changes to ‘refunded

 

Step 3: Set up the workflow

Add pre-request scripts to chain the requests in order: create payment should generate a unique idempotency key, get payment should use the payment_id saved from create, and refund should use the same payment_id. Add a collection-level pre-request script that generates a timestamp variable.

This approach works because each step validates the output before you build on it. If the collection structure in step 1 isn’t quite right, you fix it before writing tests against it.

4.  Tell Agent Mode about constraints and edge cases

Most developers write prompts that describe the happy path. The prompts that produce production-ready output also describe what should happen when things go wrong.

Add detailed error response examples to every endpoint in @my-collection. Each error response should follow this structure, and also include a short definition of what the http error code number means { error: { code, message, details } }

 

This prompt works well because it specifies:

• Exactly which error codes to include
• What each error code means in context
• The error response structure to follow
• A specific field pattern (code, message, details)

Other constraints worth mentioning in your prompts:

• Authentication requirements — “All endpoints require a Bearer token in the Authorization header”
• Rate limits — “Add a test that checks for the X-RateLimit-Remaining header”
• Pagination — “List endpoints return paginated results with page, per_page, and total fields”
• Versioning — “All endpoints are prefixed with /api/v2”

6. Use Agent Mode for debugging, not just building

One of the most underrated Agent Mode workflows is debugging. When a request fails, don’t just stare at the error — ask Agent Mode to diagnose it.

Run the requests in @my-collection and fix any that are failing. For each failure, explain what went wrong and what you changed to fix it.

 

Agent Mode can analyze error responses, check environment variable values, inspect authentication headers, and suggest fixes. I’ve seen it catch issues like:

• Expired OAuth tokens that need refreshing in a pre-request script
• Environment variables pointing to the wrong base URL
• Request body fields that don’t match the API specification
• Missing Content-Type headers

For more targeted debugging, attach the specific failing request and include the error message:

This request is returning a 401 Unauthorized. The token is set in the environment but the request still fails. Check the authorization setup, inspect the pre-request script, and fix the issue. Then verify using local mocks”

 

The recent community $250 Challenge showcased some impressive debugging workflows. The winning entry used Agent Mode to add standardized error handling across 37 healthcare API endpoints — a task that would’ve taken 16 – 22 hours manually — in about 15 minutes.

7. Generate documentation that stays in sync

I’ve always found API documentation to be the first thing that falls out of date. Agent Mode changes this because it generates docs directly from your existing collection — your actual requests, examples, and test scripts.

Generate comprehensive documentation for @my-collection. Include: a description of each endpoint’s purpose, all request parameters with types and examples, authentication requirements, example request and response bodies, and a table of all environment variables used with descriptions of what each one does.

 

Because the documentation pulls from actual collection data, it reflects the real state of your API. When you update endpoints and re-run this prompt, the docs update too.

A prompt template for documentation

Here’s a template I reuse across projects. Swap out the placeholder for your collection:

Document @my-collection with the following structure for each endpoint: 1) Purpose (one sentence), 2) HTTP method and path, 3) Required headers, 4) Request parameters (path, query, body) with types, 5) Example request, 6) Example success response, 7) Possible error responses. Add an overview section at the top that describes the API and lists all authentication methods used.

 

Patterns I’ve found useful

Start with “what can you do?”

If you’re new to Agent Mode, start here:

What tasks can I do in Agent Mode?

 

This returns a rundown of capabilities and common workflows. It’s a good way to discover features you didn’t know existed.

Use the approval workflow to your advantage

By default, Agent Mode asks for approval before modifying your data. This isn’t a speed bump — it’s a review step. Use it to check what Agent Mode plans to do before it does it. If the proposed changes don’t look right, refine your prompt instead of approving and fixing later.

If you’re confident in the output and want to move faster, you can turn on auto-run in the Agent Mode settings. I keep it off for production workspaces and turn it on when experimenting in a personal workspace.

Reference a PRD or specification

One of the most powerful features is turning a product requirements document into a working API with a single prompt. To achieve this, connect something like Jira as an MCP in Postman, or add the PRD to your local file system, then @mention the file or Jira id in your prompt. I don’t recommend pasting the entire PRD into the prompt. It is much better to retain a manageable history of product requirements somewhere outside of the conversational context of an agent.

Turn this product requirements document into an OpenAPI specification, a Postman Collection, a mock server, and tests.

 

Attach your PRD or specification as context, and Agent Mode handles the rest.

One last thing….

Curious about the Try in Agent Mode button? We wanted to make it extremely easy to share agent mode prompts in any blog you write. Check out the project on Github and add buttons to your content. Don’t forget to tag us on your favorite social media platform to show us what you built!

Resources

• Postman Agent Mode overview — Full documentation on Agent Mode capabilities and settings
• Get started with Postman AI — First steps with Agent Mode
• Agent Mode Skills — Built-in skill templates for common workflows
• Agent Mode tips and discoveries — Community thread with 14 practical tips
• $250 Community Challenge — Agent Mode prompts — Real-world prompt examples with results
• Agentmode Button — Embed Agent Mode prompt buttons on your own pages
• The new Postman is here: AI-native and built for the agentic era — Background on Agent Mode’s architecture and vision