Troubleshooting FM Agent

This section outlines what to do if FM Agent does not return the results you expect.

If results seem incorrect, incomplete, or confusing, the issue is usually related to schema configuration or field clarity.

Improve Field Annotations

If you have not added field notes, start there.

FM Agent relies heavily on field names and field notes to understand your data. If field names are abbreviated, unclear, or overloaded with meaning, the agent may interpret them incorrectly.

Add or refine Field Notes to:

• Clarify what the field represents
• Explain how values are calculated
• Define business rules
• Describe units or formats
• Explain how the field is typically used
• List allowed values if the field is restricted to specific options

If a field can only contain certain values, explicitly include them in the annotation. This helps the agent apply correct filters and avoid guessing.

---

Include Allowed Values

If a field is restricted to specific values, document them clearly.

Field Name: status
Poor annotation: Current status of the order in the system
Better annotation: Order lifecycle status. Allowed values: Draft, Submitted, Approved, Shipped, Cancelled

---

Field Name: priority_level
Poor annotation: Indicates job priority
Better annotation: Job priority. Allowed values: Low, Medium, High, Critical

Clear value definitions significantly improve query accuracy.

Document Keys and Relationships

Properly documenting primary and foreign keys is critical.

Primary Keys

Every primary key should be clearly annotated.

Field Name: id
Poor annotation: Record ID
Better annotation: Primary key for the Orders table. Unique identifier. Auto generated UUID

Foreign Keys

Foreign keys should:

• Be labeled as foreign keys
• Identify which table they reference
• Clarify the relationship type if helpful

Field Name: customer_id
Poor annotation: Customer reference
Better annotation: Foreign key referencing Customers::id. Many Orders to one Customer relationship

---

Field Name: project_id
Poor annotation: Project link
Better annotation: Foreign key referencing Projects::id. Links task to its parent project

Explicit relationship documentation helps the agent understand joins and how tables connect.

Document Internal References and Business Terminology

If your organization uses internal terminology, codes, or shorthand, describe them clearly in the field annotations.

The agent does not automatically understand company specific language, abbreviations, or legacy naming conventions.

If a field contains:

• Internal status codes
• Acronyms
• Department abbreviations
• Region codes
• SKU formats
• Custom classification systems

Document what they mean and how they are used.

Example

Field Name: region_code
Poor annotation: Sales region
Better annotation: Internal region codes. NE = Northeast, MW = Midwest, SW = Southwest, W = West

---

Field Name: job_type
Poor annotation: Type of job
Better annotation: Internal job classification. INST = Installation, SRV = Service Call, PM = Preventative Maintenance

Clear explanations of internal references help the agent interpret questions correctly and avoid misclassifying data.

Remove Irrelevant or Outdated Fields

Too many fields can reduce clarity.

If you have:

• Deprecated fields
• Old calculation fields
• Duplicate fields
• Fields no longer used in workflows

Consider unchecking them in configuration.

The cleaner the schema the agent sees, the more reliable the results.

Confirm the Correct Fields Are Enabled

If results seem incomplete:

• Expand the relevant table in configuration.
• Verify required fields are checked.
• Confirm related tables are enabled if needed.

The agent cannot query fields that are not selected.

Ask the Agent What Query It Used

If you are unsure how the agent arrived at a result, ask:

• “What query did you use?”
• “Which fields did you reference?”
• “How did you calculate that value?”

Review the generated query carefully.

Check:

• Are the correct tables being used?
• Are the correct fields referenced?
• Are joins applied correctly?
• Are filters applied correctly?
• Are allowed values being used properly?

If something looks wrong, adjust field annotations or remove misleading fields.

Understand How the Agent Interprets Questions

FM Agent attempts to match natural language to:

• Field names
• Field notes
• Table structure
• Documented relationships

Ambiguous or undocumented relationships can lead to incorrect joins.

For example:

If you have:

• id
• customer_id
• cust_ref
• client_id

Without annotations clarifying which are primary keys and which reference other tables, the agent must infer relationships.

Clear key documentation reduces errors.

Make Changes and Start a New Thread

If you:

• Modify field notes
• Enable or disable fields
• Add new tables
• Change schema

You must start a new conversation thread.

The agent learns the schema at thread creation time.

Summary

When results are unexpected:

1. Add or improve field annotations.
2. Include allowed values for restricted fields.
3. Clearly document primary keys.
4. Clearly document foreign keys and relationships.
5. Remove irrelevant or outdated fields.
6. Confirm correct tables and fields are enabled.
7. Ask the agent which query it used.
8. Start a new thread after making configuration changes.

Most accuracy issues are resolved by improving schema clarity and relationship documentation.