Browse Docs Design a High-Quality Agent

Overview

The Agentic capability is in closed beta. It’s available to Marketplace Partners and enabled per app. Contact the Marketplace team at [email protected] to request access for an app.

Build an Agentic App covers which fields to fill. This page covers the judgment: what makes an Agent worth building, and reliable once built.

Aim your first Agent at one workflow, one customer role, answers that cite records, and natural questions it answers correctly every time.

Already have a working Agent? Start with testing and diagnosis.

Start With the Customer Problem

Answer four questions before you build:

• Who has this problem? Name the role — project engineer, superintendent, project accountant.
• How often does it happen, and what does it cost today? Estimate it in hours, rework, or delays.
• Where does the data live? In Procore, in your system, or both.
• What would the customer stop doing if the Agent worked?

If you can answer each in a sentence, the workflow is ready. Confirm early that Agents can reach the Procore data your workflow needs.

Make sure the problem needs an Agent. Retrieving and restating information is a feature in your own product. Agents earn their cost by reasoning across Procore data and yours, or by completing real work.

Plan for wrong answers. Where acting on a wrong answer is costly, have the Agent cite the record behind every date, status, and amount, and route changes through Procore AI’s approval step.

Keep the First Version Narrow

Start with one workflow. A narrow Agent has fewer Tools to choose from and simpler instructions, so it picks correctly more often, finishes in fewer steps, and uses fewer of the customer’s credits. Add the next workflow after the first passes your tests.

Design Your MCP Server

An Agent picks Tools by reading their names and descriptions, so Tool design is Agent design.

• Scope the server to your workflow. Exposing your whole platform gives the Agent more to sort through.
• Say what the Tool returns and when to call it. get_data tells the Agent nothing. “Returns fabrication status and expected ship date for a steel package” tells it when to use the Tool. Use plain task language, with no internal shorthand.
• Expose outcome-level Tools, and only the ones the workflow needs. Thin create, read, update, and delete wrappers make the Agent assemble the task itself, and every extra Tool slows planning and invites a wrong pick.
• Return data the Agent can use — concise labeled fields, readable values, and stable IDs it can cite. Large or unlabeled responses make answers vague.
• Return clear errors. Reject bad input with a message that says what’s wrong, and set isError so the Agent can tell the customer what it couldn’t reach.
• Make Tools safe to retry. Keep them stateless, and make write Tools idempotent.
• Keep each call fast. One answer often takes several calls while the customer waits.

Your server must use a redirect-based sign-in. See Build an Agentic App.

Write the Agent’s Instructions

Three prompts, three jobs: the System Prompt holds the role and the rules that always apply, the Planning Prompt holds the steps and which Tools and data to use, and the Custom Prompt holds how the answer looks.

Write the workflow, not prohibitions. Prompts tend to gain a “don’t” each time the Agent surprises its author:

Answer questions about fabrication status. Don't use budget data. Don't
answer scheduling questions. Don't guess dates. Don't use web search.
Don't mention internal order numbers.

That’s five things to avoid and still no path, so the Agent improvises. A sequence defines the path:

For every fabrication question, follow these steps.

1. Identify the package or scope.
2. Call the fabrication status Tool for current status and ship date.
3. Check Procore RFIs for open items on the same scope.
4. Determine whether any open RFI blocks fabrication.
5. Answer with the status, ship date, and blockers, citing each record.

If the request falls outside fabrication tracking, say so in one
sentence and state what this Agent covers.

The closing sentence replaces most prohibitions. If you’re writing a third “don’t”, make the step before it more specific.

Say when your data comes first. Tell the Agent which source to prefer in the Planning Prompt, such as “for schedule-impact questions, combine Procore RFI records with fabrication data from your system”. Then test with questions that never mention your product.

Keep hard rules in the System Prompt, and keep it short:

You are a fabrication tracking assistant for project engineers. Be
precise and evidence-based. Never invent records, dates, or statuses.
When a field is empty or a Tool returns nothing, say so and name what
you could not reach.

Every Agent needs these four properties:

• Prompts contain no tokens, keys, credentials, or sign-in steps. Authentication runs through the platform.
• When data is unavailable, the Agent says what it couldn’t reach and invents nothing.
• The Agent has a clear scope, and a defined response for questions outside it.
• Data-backed claims cite their source records.
  
  

Test With Real Questions

Write 10 to 15 questions the way your target user would type them. “Anything holding up the steel?” is a good test. “Query the fabrication status tool, then retrieve open RFIs” does the Agent’s work for it.

Cover three kinds:

1. Data is available. The Agent answers correctly and cites its records.
2. Data is missing or ambiguous. The Agent says what it can’t determine, or asks for the detail it needs.
3. The question is out of scope. The Agent states what it covers and stops.

If your Agent writes to Procore, confirm each proposed change is correct, readable to the person approving it, and touches nothing else.

Check every answer. Trace each claim to a source record, and confirm the Agent called the right Tools and reached your data where it should.

Rerun the whole set after every change. One edited Tool description can shift behavior elsewhere.

Get a cold read. If someone who didn’t build the Agent has to learn special phrasing, so will your customers.

Diagnose by Symptom

Most vague or empty answers trace to data, not prompts. Before you rewrite an instruction, confirm the customer’s data covers the workflow, the Tool is enabled, and its response is clear. Then rerun your questions.

See Also

• Build an Agentic App — declare Agents and MCP servers on an app version.
• Choose an App Type — how Agentic fits among the capabilities.
• Procore AI — the customer experience your Agent runs in.