Prompting best practices

Best practices for writing prompts to build and edit apps.

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.

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 and refine

If the first output isn't exactly what you expected, add more info or adjust your prompt. 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.

Verify data shapes before generating code

The agent can make requests to your real resources before writing functions against them. Asking it to confirm the shape of the data first, such as column names, response structure, edge cases, helps it generate code that matches what your resource actually returns.

Run the query against @ordersDB and confirm the column names before writing the function.

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.

Plan before you build

For complex apps, ask the agent to create a wireframe or technical spec before writing any code. Reviewing the plan gives you a chance to correct the approach before the agent starts making changes.

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.

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.