Working with agents

AI tools work best when you give them clear direction. The difference between a frustrating experience and a productive one usually comes down to how you set up the work, not the tool itself. This page covers a few practices that consistently lead to better results.

​

Start with a problem statement

Before you open any tool, write down what you’re trying to accomplish in plain language. A good problem statement answers three questions:

• What do you need? Describe the end result you’re looking for.
• Who is it for? Identify who will use it and how.
• What does success look like? Define what “done” means so you can tell when you’ve gotten there.

This doesn’t need to be long. A few sentences is enough. The goal is to give yourself (and the AI) a clear target to work toward.

​

Give the agent the right context

AI tools can only work with what you give them. The more relevant context you provide, the better the output. A few things that help:

• Share examples: if you have a working version of something similar, point the agent to it.
• Name your tools and systems: tell the agent which HubSpot features you’re already using (workflows, sequences, custom properties) so it can build around them.
• Set boundaries: if there are things the solution should not do (like modify production data or change existing automations), say so up front.

​

Anchoring

Anchoring is a technique of prompting agents with critical context for the task at hand. An example would be telling the agent: “we are on HubSpot platform version 2026.03 using projects. You have access to the HubSpot Developer MCP server which allows you to search the HubSpot docs. It’s better to look something up than to assume how it works.” HubSpot’s developer documentation is AI-friendly. If you point an agent at a doc URL, the agent can access the markdown version of the document rather than the full HTML. While the HTML, CSS, and JavaScript make the site a great experience for humans, they’re mostly extra tokens for an agent to process. You can ensure the agent grabs the markdown version by either using the Developer MCP server or appending .md to any HubSpot developer documentation URL. Giving an agent links to the relevant documentation for what you’re trying to build is an effective way to anchor the agent and ensure quality. Some tools support a feature called skills, which let you package anchor context and recurring instructions into reusable files your agent can call on across sessions. See Agent skills for guidance on writing effective ones.

​

Write focused prompts

The way you frame a request shapes the quality of the output. A few patterns that consistently help:

• Scope to specifics: when building out specific features, reference a specific file, component, or function rather than describing a broad problem. “Look at the fetchData function in the MyContactCard app card and…” gives the agent a clear target.
• Reference existing patterns: instead of explaining how you want something done from scratch, point to a working example in the codebase. “Do it the same way as the DealCard component” is often faster and more accurate than a detailed specification.
• Describe goals, not solutions: explain what you’re trying to achieve and what’s going wrong, then let the agent figure out the how. Prescribing a specific implementation often locks in the wrong approach before the agent has had a chance to consider the problem.

​

Plan before building

Having the agent plan before implementation tends to produce better results than having it start building immediately. The complexity of the change is what generally determines how much the planning step helps.

• If you’re starting a new project, have the agent plan. Work with it to refine the plan before having it build.
• If you’re implementing a medium to large new feature, have the agent plan.

Over time you’ll start to identify for yourself when something warrants planning versus not.

​

Keep sessions focused

A focused session produces better results than one that expands as you go. When new ideas or follow-up tasks come up mid-session, write them down in a dedicated file rather than adding them to the current conversation. This keeps the agent working on one thing without losing the ideas. When you have multiple things to hand off at once, be explicit about priority. Telling the agent which task matters most prevents it from trying to tackle everything in parallel and producing half-finished results across the board. If the thing that came up is a research question rather than a task, you can handle it in parallel without disrupting the current session. See Parallel work for the pattern.

​

Build step-by-step

When you start with a vague end goal, you’re not adding the details necessary for the smaller foundational parts, so the AI has to make a lot of smaller decisions on its own. The result is that you’ll spend a lot of time correcting the agent’s guesses rather than building iteratively and making each piece work as you intended. Building step-by-step may feel like more work upfront, but more often than not it will lead to results that more closely match what you originally wanted.

​

Use design and technical terminology

When building a user interface for app cards and app pages, don’t just tell the AI to make something look nice. Use its language. Structural design terms like “bento box grid” or “two-column layout,” or referencing native HubSpot UI components by name like statistics, trend indicators, and status tags, will produce a better HubSpot aesthetic. Whenever possible, use CRM action buttons instead of custom UI. For example, it doesn’t make sense to have the AI write an entire custom email editor from scratch. Use a CRM action button with the action type set to send email. This pulls up HubSpot’s built-in email composer, keeps your codebase lightweight, and means you automatically inherit future HubSpot platform updates to that component.

​

Review before accepting

AI tools can produce working solutions quickly, but they can also make mistakes. Before accepting any output:

• Read the plan: does the approach match what you had in mind?
• Check the details: are property names, pipeline stages, and object types correct for your account?
• Test with real scenarios: try the solution with actual data or realistic examples before going live.
• Use dry-run mode: tools like the Agent CLI let you preview changes before committing them. Take advantage of this.

This is per-change review. As your project grows, you’ll also want to periodically review the whole codebase for issues that accumulate over time. See Review your code as the project grows.

​

Troubleshooting

If you’re not getting the results you’re expecting when working with an agent, try the following:

• Identify the technical terms for what you’re trying to accomplish. AI can help with this.
• If your project has errors, share the error message with your agent to help it debug.
• Remind the agent to search the developer documentation. This also applies if you’re integrating with a non-HubSpot system. Give your agent a link to that platform’s developer docs, and add a note about them to your agent context files.
• Start a new conversation to reset the context window.