List every Zendesk instance configured for this server, with default and currently-sticky markers. Call this once at session start to discover what instances are reachable; then use set_instance to lock onto one. For cross-instance comparisons, leave the sticky instance alone and pass instance: per-call to whichever tool you invoke.

Lock the session onto a single Zendesk instance, every subsequent call defaults to it unless you pass instance: per-call. Call this once per session; the sticky instance is how you avoid repeating yourself across dozens of tool calls. Use list_instances first if you don't know what's configured.

Returns the currently active sticky instance, or null if none has been set. Cheap sanity check, call this when you're unsure whether set_instance has been run yet.

Invalidate the in-memory cache for an instance (or scope to specific kinds: like ["triggers"]), forcing the next call to re-fetch from Zendesk. Call this after the user makes a change in the Zendesk admin UI so subsequent reads see the new state. When kinds is omitted, the per-instance HTTP client is also dropped, so edits to instances.json (rotated tokens, fixed creds) take effect on the next call without a server restart. Most other tools also accept refresh: true for one-off invalidation; reach for refresh_instance when you need to wipe several kinds at once.

Returns triggers as paginated skeletons (id, title, active, updated_at). Default limit: 100; pass cursor to walk pages, fields to project additional columns, filter for active/category/title-contains/updated-since, or verbose: true for full bodies. For "which triggers do X?" questions prefer find_triggers_by_tag / find_triggers_by_field / find_trigger_conflicts, they filter inside conditions and actions server-side and return only the matches with why_matched breadcrumbs. list_triggers without a filter on instances with thousands of triggers can be slow on first call (cold cache); subsequent calls slice from the cache and are near-instant.

Fetch one trigger by ID with full conditions and actions. Use after list_triggers / find_triggers_by_* to inspect a specific rule's body. For health audits over the whole trigger set, prefer audit_trigger_health.

Find triggers that reference a specific tag, scoped by mode: sets (action adds), removes (action removes), condition (read in current_tags), or any (union). Each match carries a why_matched breadcrumb so you can see exactly where it hit. Always reach for this before list_triggers + manual scan, it operates over the cached verbose corpus with no extra HTTP. For the broader "which tags exist at all?" question use list_tags_in_use; for a one-shot tag-hygiene audit use audit_tag_sprawl.

Find triggers that touch a named field in any condition or action, answers "which triggers reference ticket_form_id 42?", "which triggers set status to solved?", "which triggers route to group_id 7?". Optional value narrows to an exact match (string-coerced). Prefer this over list_triggers for any field-reference question, it scans the cached verbose corpus with why_matched breadcrumbs and zero extra HTTP. For impact-analysis on a custom ticket field specifically, find_field_usage checks triggers + automations + macros + views + forms in one call.

Surface pairs of active triggers that fight each other, same all-block precondition signature with contradicting effects. Two classes: field_overwrite (both write different values to the same field) and tag_set_remove_pair (one sets a tag, the other removes it). Pass trigger_id to scope to conflicts involving one rule, or include_inactive: true for cleanup audits. For a full trigger hygiene report (conflicts plus orphaned references, deactivated-but-referenced, ordering anomalies, empty rules), call audit_trigger_health instead, it bundles this analyzer with the support-kind checks. Operates over the cached verbose corpus, no extra HTTP.

Returns ticket fields (system + custom) as paginated skeletons (id, type, key, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true for full bodies including dropdown custom_field_options. For "is it safe to delete this field?" call find_field_usage, it scans every rule and form for references with why_matched breadcrumbs. For a full field hygiene report, audit_field_health bundles unused / inactive-only / empty-options / not-on-any-form checks.

Fetch one ticket field by ID with full body (dropdown options, regex, etc). For impact analysis before deletion, prefer find_field_usage.

Returns ticket forms as paginated skeletons (id, name, active, default, ticket_field_ids, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. For "is it safe to retire this form?" call find_form_usage, it scans triggers, automations, macros, and views for references. Form lists are typically tiny (single digits to dozens), so straight enumeration is usually fine.

Fetch one ticket form by ID with the full ordered list of ticket_field_ids. For impact analysis before retirement, prefer find_form_usage.

Returns custom ticket statuses as paginated skeletons (id, status_category, agent_label, active, default, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. Custom-status lists are tiny (handful of entries), so straight enumeration is fine. For deeper hygiene checks (which rules reference deactivated statuses, etc.) trace via find_triggers_by_field with field: "status".

Fetch one custom ticket status by ID. For "which rules set this status?" use find_triggers_by_field with field: "status" and the status value.

Returns trigger categories (the folders shown in the Admin UI trigger list) as paginated skeletons (id, name, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. For "are any triggers pointing at a missing category?" call audit_trigger_health, it reports orphaned_references including category orphans. To list triggers in one category, list_triggers with a category_id filter is fine.

Fetch one trigger category by ID. For category-orphan detection across triggers use audit_trigger_health.

Returns organization-level custom fields (the schema, not values) as paginated skeletons (id, type, key, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true for dropdown options. Note these are distinct from list_user_fields (user-level) and list_ticket_fields (ticket-level). For values on a specific organization, fetch with get_organization and read organization_fields.

Fetch one organization-field schema entry by ID with full body (dropdown options, regex). Distinct from a value on an organization, for that, fetch the organization and read organization_fields.

Returns user-level custom fields (the schema, not values) as paginated skeletons (id, type, key, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true for dropdown options. Distinct from list_ticket_fields and list_organization_fields. For values on a specific user, fetch with get_user and read user_fields.

Fetch one user-field schema entry by ID with full body. Distinct from a value on a user, for that, fetch the user and read user_fields.

Returns brands as paginated skeletons (id, name, subdomain, active, default, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. Plan-gated, multi-brand requires the appropriate Zendesk plan; on single-brand instances you'll see a single default brand. Brand lists are tiny, straight enumeration is fine.

Fetch one brand by ID with full body (signature template, host mapping, etc).

Returns locales enabled on the instance as paginated skeletons (id, locale, name, default, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. Use to discover which default_locale_id values are valid for list_dynamic_content variants.

Returns custom agent roles as paginated skeletons (id, name, team_member_count, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true for the full permission grid. Plan-gated, custom roles require Enterprise; degrades to upstream_error on lower plans. Distinct from system roles (admin, agent, end-user).

Fetch one custom role by ID with the full permission grid. Enterprise-plan-gated.

Returns business-hours schedules as paginated skeletons (id, name, time_zone, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true to inline weekly intervals. Plan-gated, schedules require Professional+. For "what are the actual business hours?" call list_business_hours with a schedule_id, it composes intervals + holidays, which the schedule list alone doesn't cover.

Fetch one schedule by ID, including its weekly intervals. For schedule + holidays in one call use list_business_hours, Zendesk holidays live on a separate sub-resource and get_schedule alone won't surface them.

Composite that returns the weekly intervals and the holidays for one schedule in a single response. Reach for this rather than get_schedule when answering "when is this schedule open?", Zendesk splits hours and holidays across two endpoints; this tool joins them. Plan-gated alongside schedules themselves.

Returns SLA policies as paginated skeletons (id, title, position, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true for full filter conditions and policy_metrics. Plan-gated, SLAs require Professional+. For "which SLA fires on group X?" call find_group_usage, it includes SLA filter conditions in its scan.

Fetch one SLA policy by ID with full filter and policy_metrics. For impact analysis on a referenced group, use find_group_usage.

Returns webhooks (the modern outbound integration mechanism) as paginated skeletons (id, name, status, endpoint, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. For per-webhook delivery history use list_webhook_invocations with a webhook_id, that's where you'll find request/response timing and HTTP status. list_targets is the legacy equivalent, most modern instances should be on webhooks.

Fetch one webhook by ID with full body (auth, signing key, subscriptions). For delivery history, use list_webhook_invocations.

Returns the delivery history for one webhook, every fire with http_status, request/response timing, and outcome. Default limit: 100; pass cursor, fields, filter. The right tool for "is this webhook actually working?", failures and slow responses surface here. For instance-wide configuration changes (not webhook deliveries), use list_audit_logs.

Returns legacy outbound targets (URL/email integration endpoints, deprecated by Zendesk in favor of webhooks) as paginated skeletons (id, type, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. Modern instances should use list_webhooks, surface targets only for migration audits. Targets have no per-call invocation log; use list_audit_logs for change history.

Fetch one legacy target by ID with full body. For new integrations prefer get_webhook.

Returns dynamic content items (the localizable snippets used in macros, triggers, automations) as paginated skeletons (id, name, default_locale_id, variants_count, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true to inline variant bodies per locale. Plan-gated, Professional+; degrades to upstream_error on lower plans. Cross-reference variant locales with list_locales to spot missing translations.

Fetch one dynamic content item by ID with all locale variants. Plan-gated to Professional+.

Returns instance-wide configuration audit logs as paginated skeletons (id, source_type, actor_name, action, change_description, created_at), every admin/config change with attribution. Enterprise-plan-gated; on lower plans returns upstream_error with the underlying http_status (403/404). Default limit: 100; pass cursor, fields, filter (server-side filters for source_type/action are honored). For per-ticket field changes use get_ticket_audits, this tool is admin-config only, not ticket-level.

Returns skill-based-routing attribute definitions (e.g. "Skill", "Language", "Region") as paginated skeletons (id, name, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. Plan-gated, requires omnichannel routing; degrades to upstream_error (403/404) when the feature isn't enabled. For the values inside one attribute use list_routing_attribute_values; for the legacy "skills" entry-point use list_skills.

Fetch one routing attribute definition by ID. Plan-gated, degrades to upstream_error on 403/404 when omnichannel routing is off. For the attribute's values, call list_routing_attribute_values.

Returns the values defined under one routing attribute (e.g. the actual skills under a "Skill" attribute) as paginated skeletons (id, attribute_id, name, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. Plan-gated, degrades to upstream_error when omnichannel routing is off. To see which agents have a given value, use list_agent_skill_assignments per agent.

Convenience wrapper that resolves a "skills"-like routing attribute and returns its values as skeletons. Pass attribute_id to target one specifically, or attribute_name (case-insensitive; defaults to "skill"/"skills"). Modern Zendesk has no /skills.json endpoint, this tool exists because LLMs ask for "skills" by name; under the hood it's list_routing_attribute_values against the skill attribute. Plan-gated. For agent assignments use list_agent_skill_assignments.

Returns the routing-attribute values an agent holds (i.e. which skills/queues that user is eligible for) as paginated skeletons. Backed by /api/v2/users/{user_id}/instance_values.json, the canonical SBR-assignment endpoint. Plan-gated, degrades to upstream_error when omnichannel routing is off. Scope-gated because it touches user data (config_plus_audits or full). For attribute/value catalogs (not assignments), use list_routing_attributes / list_routing_attribute_values.

Returns tickets as paginated skeletons (id, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true for full bodies. Scope-gated, requires the instance to be configured at scope config_plus_audits or full; on config you get a scope_blocked envelope. For specific lookups prefer search (full Zendesk query syntax: type:ticket status:open), list_tickets over a busy instance pulls everything and is rarely what you want. For a single ticket's context use get_ticket with include_comments / include_audits.

Fetch one ticket by ID; optionally inline its include_comments thread and/or include_audits history in the same call. Scope-gated (config_plus_audits or full); blocked calls return scope_blocked. Use the inline includes when you need conversational context, they save a round-trip vs. calling get_ticket_comments / get_ticket_audits separately. For pure SLA / responsiveness numbers, get_ticket_metrics is cheaper than parsing audits.

Return the comment thread for one ticket as paginated skeletons (id, type, author_id, body, html_body, public, created_at). Scope-gated (config_plus_audits or full). Pass verbose: true for via-channel info and attachments. For "what changed on this ticket and why?" use get_ticket_audits instead, comments only carry the textual conversation, audits carry rule attribution.

Returns the audit history for a ticket, every state change with rule attribution and event timestamps. Defaults to limit: 100 events; pass since to bound by date, event_types: ["Change"] to skip Comment events entirely (much smaller response). Scope-gated, requires config_plus_audits or full; at config_plus_audits Comment-event bodies are auto-redacted. Use this for forensic debugging ("why did this macro send the ticket to the wrong group?"), via.source on each audit names the trigger / macro / app that made the change. For pure timing data, get_ticket_metrics is cheaper.

List side conversations (Collaboration add-on) attached to a ticket as paginated skeletons. Plan-gated, on instances without the Collaboration add-on the call degrades to a structured upstream_error envelope with the underlying http_status, not a thrown failure. Also scope-gated (config_plus_audits or full). Use to surface the parallel email/Slack thread on a ticket; for the main public conversation use get_ticket_comments.

Fetch the ticket_metric record for one ticket, reply count, reply/resolution times, reopens, station counts, on-hold time. Scope-gated (config_plus_audits or full). Use this for SLA / responsiveness questions; use get_ticket_audits for "why did this happen?" Audits carry rule attribution and field-level changes; metrics carry only the timing aggregates and are much cheaper.

Returns users as paginated skeletons (id, name, email, role, organization_id, active, timestamps). Default limit: 100; pass cursor, fields, filter, or verbose: true. Scope-gated, requires config_plus_audits or full; on config returns scope_blocked. For finding a specific user prefer search (e.g. type:user email:foo@bar.com), full enumeration on a large customer base is rarely the right call. For an agent's SBR skill values, use list_agent_skill_assignments.

Fetch one user by ID with full profile details. Scope-gated (config_plus_audits or full). For lookup by email or other criteria, use search with type:user.

Returns organizations as paginated skeletons (id, name, domain_names, timestamps). Default limit: 100; pass cursor, fields, filter, or verbose: true. Scope-gated, requires config_plus_audits or full. For finding a specific organization prefer search with type:organization name:"Acme"; full enumeration is expensive and rarely needed. For org-level custom field metadata see list_organization_fields.

Fetch one organization by ID. Scope-gated (config_plus_audits or full). For lookup by name or domain, use search with type:organization.

Returns agent groups as paginated skeletons (id, name, description, default, deleted, timestamps). Default limit: 100; pass cursor, fields, filter, or verbose: true. Group lists are typically small (dozens), so this is usually fine to call without filtering. For "is it safe to delete this group?" call find_group_usage, it scans triggers, automations, views, and SLA policies for references with why_matched breadcrumbs.

Fetch one group by ID. For impact analysis before deletion, prefer find_group_usage over fetching and inspecting manually.

Returns macros as paginated skeletons (id, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. For "which macros are unused?" call find_unused with kind: "macros", it consults Zendesk's usage_30d stats and gives a confident answer where it can. For tag / field impact across macros + triggers + automations + views, use find_field_usage or audit_tag_sprawl.

Fetch one macro by ID with full actions. For "is this macro safe to delete?" prefer find_unused; for impact analysis on a referenced field/form/group, use find_field_usage / find_form_usage / find_group_usage.

Returns views as paginated skeletons (id, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. For "which views are unused?" call find_unused with kind: "views", it uses Zendesk's usage_30d to give a confident answer. For impact analysis on a field/form/group referenced by views, use find_field_usage / find_form_usage / find_group_usage.

Fetch one view by ID with full conditions. For "is this view used?" prefer find_unused; for what fields/forms/groups it references, use the corresponding find_*_usage analyzer.

Returns automations (time-based rules) as paginated skeletons (id, title, active, updated_at). Default limit: 100; pass cursor, fields, filter, or verbose: true. Automation firing data is not exposed by the Zendesk API on standard plans, so find_unused returns indeterminate for automations rather than guessing. For tag / field reference questions across automations + triggers + macros, prefer find_field_usage or audit_tag_sprawl.

Fetch one automation by ID with full conditions and actions. For impact analysis on referenced fields/forms/groups, use the corresponding find_*_usage analyzer.

Run a Zendesk v2 Search query across tickets, users, organizations, and groups; returns mixed-type results in their native shape. Use the standard query syntax (e.g. type:ticket status:open, type:user email:foo@bar.com, type:organization tags:vip). Always reach for this before list_tickets / list_users / list_organizations when you're looking for specific records, the search index is much faster than enumeration. Scope-gated when results include tickets/users/orgs (config_plus_audits or full).

Fetch the current account-overview snapshot for Zendesk Talk (voice channel), average wait/handle time, calls in queue, agents online. Plan-gated to instances with Talk enabled; degrades to a structured upstream_error envelope otherwise. Snapshot only, for historical voice analytics use the Zendesk Explore product directly.

List Zendesk Chat conversations as paginated items in their native shape (no skeleton projection, chat payloads are already compact). Default limit: 100; pass cursor, fields, or filter. Plan-gated, degrades to upstream_error on instances without the Chat add-on. Scope-gated when chats include user/ticket data (config_plus_audits or full).

Find every reference to a custom ticket field across triggers, automations, macros, views, and ticket forms, returns references with why_matched breadcrumbs and reference_count. The right tool for "is it safe to delete this field?" Operates over the cached verbose corpus, no extra HTTP unless refresh: true. For a full field-hygiene report (unused / inactive-only / empty options / not on any active form), use audit_field_health instead, it bundles this analyzer.

Find every reference to a ticket form across triggers, automations, macros, and views, returns references with why_matched breadcrumbs. The right tool for "is it safe to retire this form?" Operates over the cached verbose corpus, no extra HTTP. For broader form hygiene (forms with no active rules, etc.), audit_field_health covers the form-side checks too.

Find every reference to an agent group across triggers, automations, views, and SLA policies, returns references with why_matched breadcrumbs. The right tool for "is it safe to delete this group?" Operates over the cached verbose corpus, no extra HTTP unless refresh: true. For broader trigger-orphan detection (including dangling group ids), audit_trigger_health checks group, form, field, and category orphans in one pass.

Inventory every tag referenced across triggers, automations, and macros, with where-used rows (kind, id, title, mode), suspected near-duplicates (case-insensitive, separator-stripped, Levenshtein-1), and a set_only flag for tags written but never read in conditions. Operates over the cached verbose corpus, no extra HTTP unless refresh: true. For a full tag-sprawl audit (clusters of dupes, top-N usage distribution) call audit_tag_sprawl, it bundles this analyzer with clustering. For "which rules touch one specific tag?" use find_triggers_by_tag.

Detect unused macros and views by reading Zendesk's usage_30d stats; returns confident verdicts only where data exists. kind: "triggers" and kind: "automations" always return indeterminate, firing data is not exposed by the Zendesk API on standard plans, so the tool refuses to guess. For trigger / automation cleanup, combine find_trigger_conflicts, audit_trigger_health, and find_field_usage / find_group_usage instead.

One-call dashboard for a Zendesk instance, counts of every config object (active/inactive splits where applicable) plus headline metrics (oldest/newest trigger, biggest trigger category, deactivated-but-positioned triggers). Run this first when picking up a new client engagement, it primes the cache for everything that follows, so subsequent analyzer / audit calls are essentially free. Tolerates per-kind upstream errors (plan-gated endpoints don't fail the whole composite); failures are listed in notes.

Composite ticket-field hygiene report: flags fields referenced by nothing, fields referenced only by inactive rules, dropdown/multiselect fields with empty option lists, and custom fields not on any active form. Skips system fields (subject, status, priority, etc.). The right starting point for field-cleanup work, bundles find_field_usage plus the option-list and form-coverage checks. Tolerates per-kind upstream errors with notes.

Composite trigger-hygiene report: conflicts (overlapping preconditions with contradicting effects), deactivated_but_referenced (dead triggers still chained), orphaned_references (pointing at missing groups/forms/fields/categories), ordering_anomalies (inactive triggers in early slots, duplicate positions), and empty_rules. The right starting point for trigger cleanup work, bundles find_trigger_conflicts plus the orphan/order/empty checks in one call. Tolerates per-kind upstream errors on support kinds (notes listed in notes); a missing trigger list is fatal.

Composite tag-hygiene report: full inventory (per-tag where-used, dupe suspects, set_only flag), clustered groups of suspected duplicates (vip / VIP / v_i_p collapse together), set_only tags written but never read, and a top-N usage distribution. The right starting point for tag-cleanup work, bundles list_tags_in_use with clustering. For "which rules touch tag X?" use find_triggers_by_tag instead. Tolerates per-kind upstream errors with notes.