> For the complete documentation index, see [llms.txt](https://help.felt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.felt.com/felt-ai/prompting-tips.md). # Prompting tips Felt AI shows up in a few places, and each one works a little differently. This page collects prompting tips by surface: the [AI assistant](/felt-ai/ai-assistant.md), [Extensions](/developer-platform/extensions.md), [Custom popups](/developer-platform/custom-popups.md), and [SQL queries](/data-sources/cloud-sources/sql-queries.md). ## Tips that apply everywhere **Use exact names.** Generic references create ambiguity. Use actual layer names, attribute names, and values from your data. **✅ Good:** > Filter the "permits" layer to show only records where permit\_type is "residential" and status is "pending". ❌ **Weak:** > Show me the pending residential permits. **Handle edge cases.** Say what should happen when data is missing or a filter returns nothing. > If assessed\_value is null, display "Not available" instead of blank. **Describe the format you want.** When output format matters, give an example. > Format dates as March 15, 2025 not 2025-03-15. Display currency as "$1,250,000" with commas and dollar sign. **Build incrementally.** Complex requests built in one prompt usually need a lot of fine-tuning. Small, testable steps are easier to verify, easier to debug, and let you adjust direction based on what's working. When something isn't right, refine rather than starting over. ## AI assistant The [AI assistant](/felt-ai/ai-assistant.md) finds data, runs analysis, and styles your map from conversation — you describe what you're trying to learn or show, and it delivers results on the map. ### Describe the goal, and let it work Give the assistant your intent and constraints, not a step-by-step procedure. It can see your layers, connected data sources, and Felt's data libraries, and it will pick the data, analysis, and styling to match your goal. **✅ Good:** > I'm evaluating flood exposure for our Houston portfolio. Add FEMA flood zones, identify which of our properties fall in high-risk zones, and style the result so risk levels are obvious at a glance. ❌ **Weak:** > Add a layer. Now filter it. Now change the colors. ### Reference data with @ Type **@** to point the assistant at exactly the layer or data source you mean — especially useful when names are similar or your workspace is large. > Compare @Census Tracts with @Store Locations and highlight tracts with no store within 2 miles. ### Iterate in conversation The assistant keeps the context of your conversation, so refine the way you'd direct a teammate: > Make the high-risk zones more prominent and mute everything else. > > That classification hides the variation I care about — try quantiles instead. > > Zoom to where the risk is concentrated. ### Keep conversations focused Start a **New chat** when you switch to an unrelated task. A conversation about one problem gets better results than one carrying leftover context from three different tasks. ### Ask it to explain If you want to understand or verify what it did: > Walk me through how you calculated that risk score. > > Which data source did that layer come from? ## Extensions [Extensions](/developer-platform/extensions.md) are interactive tools where users click, filter, and explore. In the Extensions editor, Felt AI drafts JS SDK code you can read, edit, and run. Think: "when the user does X, show them Y." **What to specify:** * The trigger event (click, select, filter change) * What layers are involved * What should display in the panel * What visual feedback appears on the map * How to reset or clear previous results **✅ Good:** > Create an interactive tool where I can click on any school to find nearby parcels. When I click a school: > > 1. Draw a 500-meter buffer around it > 2. Spatially filter the parcels within that radius > 3. Show a panel with the school name, count of nearby parcels, and a list of those parcels with their zoning type and assessed value > 4. Clear previous results when I click a different school ❌ **Weak:** > Find parcels near schools. For complex tools with multiple interactive features, number your requirements — each one is small and testable, and the AI follows the logic better than a run-on description. {% hint style="info" %} **Tip:** responses can give general guidance and recommendations if you specify "don't write code" in your prompt > Don't write code, but how would I filter and analyze my parcel layer based on selecting a neighborhood in my boundaries layer? > {% endhint %} {% hint style="info" %} **Tip:** you can prompt for more verbose logging to appear in the console or extension panels when debugging {% endhint %} **When refining**, check each layer of functionality — do clicks, filters, and selections behave correctly? Are calculations returning expected results? — and fix specifically: > The count isn't updating when I change the filter — can you check why? > > Remove the chart, just keep the attribute summaries. ## Custom popups [Custom popups](/developer-platform/custom-popups.md) display formatted information when users click a feature. Felt AI drafts the HTML, CSS, and JavaScript, which you can edit directly. **What to specify:** * Exact attributes to show and their format * Any conditional styling or specific branding (color-code status values, show icons) * Links or images to include **✅ Good:** > Create a popup for this layer showing: > > * Address as a bold heading > * Price formatted as currency > * Bedrooms and bathrooms as "3 bd | 2 ba" > * Square footage with comma separator > * A link to "View listing" using the listing\_url attribute ❌ **Weak:** > Add a popup for properties. Preview in both desktop and mobile modes before saving — layout requests like "keep it to two lines on mobile" work well. ## SQL queries [SQL queries](/data-sources/cloud-sources/sql-queries.md) let you ask spatial questions of your cloud database. Felt AI translates your question into SQL you can inspect, edit, and run, and results become a map layer. **What to specify:** * The spatial relationship you're looking for (within distance, intersects, contains) * Which tables to use * Any filters or conditions * What attributes to include in results {% hint style="info" %} **Tip:** if you're unsure about your schema, ask first > What tables do I have related to emergency response? What fields are available? > {% endhint %} **✅ Good:** > Find all fire stations within 2 miles of areas where response times exceeded 10 minutes last year. Join with the incidents table and show the count of slow responses per station. ❌ **Weak:** > Show me fire station coverage. If a query looks slow or returns too much, ask the AI to optimize it or add limits — and review the SQL it wrote; it's yours to tune. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.felt.com/felt-ai/prompting-tips.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.