Skip to main content
Glama
FreeScout MCP Server

FreeScout MCP Server

Search FreeScout Tickets

freescout_search_tickets
Read-only

Search FreeScout tickets by subject, customer email, assignee, status, tag, or date filters; look up a ticket number and preview the latest message.

Instructions

Search for FreeScout tickets with explicit filter parameters. Text search is subject-only (FreeScout has no message-body full-text search): use subject (or its alias textSearch) to match the conversation subject, customerEmail to filter by the customer, and number to look up a single ticket. Use assignee: "unassigned" for unassigned tickets, or assignee: number for a specific user. Supports relative time filters like "7d", "24h". Use includeLastMessage: true to get a preview of the most recent message for each ticket.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "freescout_search_tickets"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagNoFilter by FreeScout tag name.
pageNo
stateNo
numberNoLook up a single conversation by its ticket number.
statusNo
subjectNoFilter by conversation subject (partial match).
assigneeNo
pageSizeNo
mailboxIdNo
textSearchNoAlias for `subject`: matches the conversation subject only, not message bodies.
createdSinceNo
updatedSinceNo
customerEmailNoFilter by the customer email address on the conversation.
includeLastMessageNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.2.0
    • addedInput schema / properties / tag
      Added value: +{
      +  "description": "Filter by FreeScout tag name.",
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. Changed4 schema fields changedv3.1.0
    • addedInput schema / properties / customerEmail
      Added value: +{
      +  "description": "Filter by the customer email address on the conversation.",
      +  "type": "string"
      +}
    • addedInput schema / properties / number
      Added value: +{
      +  "description": "Look up a single conversation by its ticket number.",
      +  "type": "number"
      +}
    • addedInput schema / properties / subject
      Added value: +{
      +  "description": "Filter by conversation subject (partial match).",
      +  "type": "string"
      +}
    • addedInput schema / properties / textSearch / description
      Added value: +"Alias for `subject`: matches the conversation subject only, not message bodies."
  3. Changed1 schema field changedv3.0.1
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  4. First observedv2.1.1

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, openWorld, and non-destructive, so the safety profile is covered. The description earns credit for a genuinely useful behavioral disclosure beyond that: text search is subject-only because FreeScout has no message-body full-text search, plus the includeLastMessage preview behavior and relative-time filter support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical limitation (subject-only search) is front-loaded, and each subsequent clause maps to a distinct parameter or mode rather than repeating itself. The prose is dense and slightly run-on, but no sentence is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, zero-required search tool with no output schema, the description covers the high-value filters but omits pagination (page/pageSize), status/state/tag/mailboxId semantics, and any indication of what a result contains or how it is ordered or paged. Enough to call it correctly for common cases, not enough for full use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 36%, so the description must carry weight, and it does add real meaning for subject/textSearch (partial match, subject only), customerEmail, number, the special assignee values, and the '7d'/'24h' time format. But it is silent on tag, page, pageSize, mailboxId, status, and state, leaving roughly half the 14 parameters without documentation in either place.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Search for FreeScout tickets') and immediately scopes it to explicit filter parameters, which separates it from listing tools. However, it does not distinguish itself from freescout_get_ticket even though it offers a 'number to look up a single ticket' mode that overlaps with that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete selection guidance for the main modes: subject/textSearch for text matching, customerEmail for customer filtering, number for single lookups, assignee 'unassigned' or a numeric user ID, and relative time filters like '7d' or '24h'. What is missing is an explicit exclusion or pointer to alternatives, notably that number lookup overlaps with freescout_get_ticket.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.