TimeZest Agents & Teams

TimeZest Agents & Teams

Every TimeZest scheduling request books against a resource — either an individual agent or a team. Picking the right one is the first step of any booking, and TimeZest treats agents and teams differently enough that the choice matters.

Domains & Tools

TimeZest's MCP server is navigation-based. Enter a domain with timezest_navigate before its tools are available; return with timezest_back.

Agents — individual technicians

| Tool | Purpose | |------|---------| | timezest_agents_list | List all agents (technicians) available for scheduling | | timezest_agents_get | Get full detail for one agent by agentId |

timezest_agents_list accepts pageSize (1–100, default 50) and a filter TQL string (e.g. active:true AND department:"IT Support").

Teams — round-robin / shared pools

| Tool | Purpose | |------|---------| | timezest_teams_list | List all teams available for scheduling | | timezest_teams_get | Get full detail for one team by teamId |

timezest_teams_list accepts pageSize and a filter TQL string (e.g. active:true).

Agent vs Team — which to book

| Situation | Book | |-----------|------| | The dispatcher named a specific technician | An agent | | The customer needs the soonest slot from any qualified tech | A team (round-robin) | | Work requires a named specialist (e.g. a security lead) | An agent | | Tier-1 / general support where any tech will do | A team |

A team request shows the customer combined availability across the team's members and lets TimeZest assign whoever the round-robin lands on. An agent request shows only that one technician's calendar.

Common Workflows

Resolve a technician by name

1. timezest_navigate to agents.
2. Call timezest_agents_list. Use a filter like active:true to

skip deactivated technicians.

1. Match the dispatcher's name against the result. If two agents have

similar names, call timezest_agents_get on each to disambiguate.

1. Carry the resolved agentId forward to the scheduling request.

Resolve a team

1. timezest_navigate to teams.
2. Call timezest_teams_list with active:true.
3. Match by team name (e.g. "Network", "Onsite Dispatch").
4. Carry the resolved teamId forward.

Edge Cases

• Inactive resources — timezest_agents_list and

timezest_teams_list can return deactivated entries. Always filter active:true unless you specifically need historical resources.

• Name collisions — Two technicians named "Chris" is common. Never

pick the first match; confirm with _get.

• Pagination — Large MSPs exceed the 50-row default. Raise

pageSize to 100 or page through before assuming a name is absent.

Best Practices

• Always resolve agents and teams by name through a list call in the

current session — do not hard-code or cache IDs across days.

• Prefer a team for "soonest available" requests; an agent only when a

named person is genuinely required.

• Confirm ambiguous matches with _get before booking.

Related Skills

• [scheduling](../scheduling/SKILL.md) — Booking technicians against PSA tickets
• [resources](../resources/SKILL.md) — Querying agents and teams together as one pool
• [appointment-types](../appointment-types/SKILL.md) — Choosing the right appointment type