Agent Tools

The Freshdesk agent provides 6 tools for searching and analyzing support tickets:

Tool	Description	Key Parameters
`search_tickets`	Natural-language search across Freshdesk tickets.	`query`, `limit`
`list_recent_tickets`	List tickets created in the last N days, with detailed views auto-fetched for the most recent tickets.	`days`
`get_ticket_details`	Retrieve full ticket context including description, status, priority, and a generated summary of conversations.	`ticket_id`, `include_conversations`
`get_ticket_conversations`	Retrieve all conversations for a ticket, labeled as Customer Reply, Agent Reply, or Internal Note.	`ticket_id`
`search_tickets_advanced`	Structured search with status/priority/company/agent/tag filters plus a raw `custom_query` for custom fields.	`status`, `priority`, `company`, `agent`, `tags`, `created_after`, `custom_query`, `limit`, `sort_by`, `sort_order`
`get_tickets_by_company`	List a company’s tickets with a priority breakdown, sorted by priority.	`company_name`, `days`

Status & Priority Codes

Freshdesk uses numeric codes for status and priority. The agent accepts either the code or the human-readable name and translates it into a search query:

Status	Code
Open	2
Pending	3
Resolved	4
Closed	5
Waiting on Customer	6

Priority	Code
Low	1
Medium	2
High	3
Urgent	4

Structured Search

search_tickets_advanced builds a Freshdesk search query from its structured parameters:

Filter	Query Syntax	Notes
Status	`status:{code}`	e.g., `status:4`
Priority	`priority:{code}`	e.g., `priority:3`
Company	`cf_portal_name_ak:'{name}'`	Matches the company/portal custom field
Agent	`responder_name:'{name}'`	Matches the assigned responder
Tags	`tag:'{tag}'`	One clause per tag
Created After	`created_at:>'{YYYY-MM-DD}'`	Date-based filter
Custom	`custom_query`	Raw Freshdesk search syntax, combined with the structured filters

The default query when no filters are provided is status:2 (Open).

Schema-Aware Custom Field Search

When the connector initializes, it loads your Freshdesk ticket fields and injects the custom-field schema into the agent’s system prompt. This lets the agent build correct custom_query filters for fields like cf_tenantid, cf_service_impact_ak, cf_portal_name_ak, and nested category fields.

Nested fields must be queried using the subcategory value (not the parent)
Unindexed fields (e.g., cf_resolution_summary, cf_category, cf_sub_category, cf_root_cause) are not searchable by name — the agent is instructed to use custom_string instead
If a custom-field query returns 0 results, the agent retries up to 2 additional attempts with a schema-correction prompt

Auto-Fetch Behavior

When listing or searching tickets, the agent automatically fetches full details for a subset of the results so the answer includes rich context, not just ticket summaries.

Setting	Default	Description
`freshdesk_auto_fetch_count`	3	Tickets to fetch details for in an initial sweep

For search_tickets_advanced, details are fetched for the top tickets by priority when the result limit is within freshdesk_auto_fetch_count.

Manual Override

Prefix your query with /freshdesk to route directly to the Freshdesk agent, bypassing the workflow classification:

/freshdesk What support tickets are open about the VPN connector?

Citation System

Every ticket found during a session is tracked and appended to the response as a Sources section of clickable ticket URLs (sorted numerically, deduplicated):

Sources:
- https://company.freshdesk.com/a/tickets/50123
- https://company.freshdesk.com/a/tickets/50145

Hallucination Protection

After the agent finishes, a FreshdeskResponseValidator checks every ticket ID cited in the response against the IDs actually retrieved by the tools:

Unverified ticket IDs referenced in the response are stripped out automatically
A warning is logged whenever the response is corrected
If no tickets were found or the response contains no valid ticket references, the agent reports an insufficient result rather than guessing

Configurable Limits

Setting	Default	Description
`freshdesk_auto_fetch_count`	3	1–50, hot-reload
`timeout_freshdesk_agent`	30s	Config default agent timeout
connector timeout	45s	Agent execution timeout

API Endpoints

All endpoints require admin authentication.

Endpoint	Method	Description
`/api/connectors/freshdesk`	`GET`	Get Freshdesk connector status and configuration
`/api/connectors/freshdesk`	`PATCH`	Enable/disable the Freshdesk connector (hot-reload)
`/api/connectors/freshdesk/live-query`	`PATCH`	Enable/disable the live-search agent
`/api/connectors/freshdesk/test-connection`	`POST`	Test Freshdesk connectivity and credentials