Prompting best practices

Best practices for writing prompts to build and edit apps.

Crafting high-quality prompts results in apps that are more aligned with your needs, functionally complete, and working well. Incomplete or nonspecific prompting can result in more iteration, wasted time, and higher cost as the agent uses more tokens.

Consider the following best practices for writing effective prompts in the app builder.

Reference resources by name

You can @ mention a resource in your prompt to point the agent at a specific connection.

Use the @Customer Support Tickets Database resource to power the support tickets table.

Merge the data from @S3 Bucket and @AWS Lambda and show the data from both in a single chart.

Give as much context as possible

Be as specific as you can about the type of app you want to create or the edits you want to make. The more detail you include about what you're trying to build, the better the agent can do on the first pass.

Build me a dashboard that helps me manage PTO requests. Time-off requests are tracked in the @ptoRequests resource. Utilize the /approve and /deny endpoints. Create one page for approving and denying requests, and create another page that uses @googleCalendar to show the requests that conflict with product launches.

Upload key files

Use the file upload option to add additional context to your building session.

I uploaded a PDF of our brand guidelines. Update this app so that it uses the colors, designs, and copy guidelines from the file.

The attached file is the specification for our internal API at @brothersTransport. Use it to build an app that tracks our transportation requests.

Iterate manually and with the agent

If the first output isn't exactly what you expected, try to reframe your prompt and add more context. You can also manually edit your app and come back to the agent to continue where you left off. Working with the agent is designed to be an iterative process.

I made some changes manually. Can you verify that everything is still working?

Be specific about resource nuances

Databases (Retool Database, Postgres, MySQL, etc.) can be queried or modified using similar patterns, so the agent can reliably generate SQL queries. On the other hand, API request structures and specifications can vary widely between endpoints. Giving details about how your system is configured, or pasting API documentation into your prompt helps the agent understand the structure.

For REST API resources, attach an OpenAPI or Swagger specification on the resource configuration page. With a specification attached, the agent gets typed methods for every endpoint and knows the expected request and response shapes. Without one, the agent can only make untyped requests, and might need to make several requests by trial and error.

Use the @ptoRequests resource to manage requests using the /approve and /deny endpoints.

Create your data model before you build

For apps that create or maintain production data, switch to Plan mode and ask the agent to propose the data model before building or editing the app.

A useful plan should name every existing or proposed resource. If the app uses a database, the plan should identify the relevant schema and tables. For each table, the plan should include information about:

• The type of data the table stores.
• What one row represents (such as a refund record or an inventory item).
• Columns and column data types.
• Primary and foreign keys.
• Constraints and relationships between tables.

The plan should clearly distinguish existing tables and fields from proposed changes. Related records should be connected through stable IDs rather than changeable display values such as names.

Learn more about plan mode.

Before building, propose a data model for this app. Identify the core entities, tables, primary keys, foreign keys, relationships, and the authoritative source for each field. Explain how the model will support future additions and imports without creating duplicates. Do not create tables, queries, or UI until I approve the model.

Example 1: Model related records before building

Consider an app that tracks people, interviews, and findings. A person can participate in more than one interview. A finding can be supported by several interviews, and one interview can support several findings.

If the agent repeats a person's name and details inside every interview or finding, later edits can create several versions of the same person. If it stores only one interview ID on each finding, the model cannot represent the full entity relationship.

A comprehensive data model stores each person once, stores each interview once with the person ID and interview date, stores each finding once, and connects findings to interviews through a separate entity relationship.

Before building the customer feedback tracker, propose the data model. A person can participate in multiple interviews. Each interview has an interview date. A finding can be supported by multiple interviews, and an interview can support multiple findings. Store each person, interview, and finding once. Use stable IDs and a linking table for the evidence relationship. Do not store full transcripts. Wait for my approval before creating the schema or UI.

Example 2: Separate a UI change from a data change

A builder could ask the agent to simplify an overview page or move administrative information into a different view. That sounds like a presentation change, but the agent may also rewrite queries, introduce a new resource, or change where information is stored. If the authoritative source is not clear, records can disappear from the UI or be copied into a second structure.

Prompt the agent to explicitly separate presentation work from schema and data work. Ask the agent to first identify the current source for every affected field and state what it plans to preserve.

Treat this as a UI organization change only. Before editing, inspect the current tables, queries, and views, then identify the authoritative source for every field affected. Do not change the schema, rename fields, migrate records, or write data. Tell me which pages, queries, and views will change, what will remain untouched, and wait for my approval.

Example 3: Plan a safe CSV import

Adding records from a CSV is another point where the data model matters. Before importing anything, the builder needs to know how a row will match an existing record, which values may be updated, what happens when fields conflict, and whether blank values can replace existing information.

Instruct the agent so that if no reliable matching key exists, the agent should stop and ask for one rather than guessing from a display name. The agent should also preview the result before writing data so the builder can review inserts, updates, conflicts, and possible duplicates.

Before importing this CSV, inspect its columns and compare them with the existing data. Propose the stable key used to match existing records. Preview which rows would be inserted, updated, skipped, or flagged as conflicts. Do not overwrite a nonempty existing value with an empty CSV value. Do not create duplicates or write any changes until I approve the preview.

Plan before you build

For complex changes, use Plan mode to ask the agent to create a wireframe or an outline of your app before writing any code. Review the plan, and correct the approach either manually or by prompting the agent. This gives you further control over the actions that the app building agent takes.

Learn more about plan mode.

Create a wireframe for this app before building it.

Write a technical spec for this feature first, then wait for my approval before making any changes.

Ask for specific UI components

Apps are built with a defined set of libraries. If you have a specific component in mind, name it instead of describing it. For example, asking for a Sheet is more precise than asking for a side panel.

Use a Sheet for the edit form so it slides in from the right.

Scope requests to one feature at a time

The agent works through tasks in steps, pausing to check in as it goes. Breaking a large request into smaller, focused prompts—one feature or section at a time—gives you more control and leads to more complete results than asking the agent to build an entire app in a single message.

When making edits, naming the specific page or area you want changed helps the agent scope its work.

I want you to create an app that helps me manage employee PTO. First, use the @ptoRequests resource to help me view outstanding and historical requests.

Now, add functionality that enables me to approve and deny new requests.