Skip to main content
Glama
crisphive

Crisphive

Official
by crisphive
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Add a technician

createTechnician

Add a technician to your business—link an existing user or create a new identity, assign buddies/service areas, and notify via email or SMS.

Instructions

Add a technician

Creates a technician membership under the current business. If the phone/email matches an existing user, their account is linked. Otherwise a new user identity is created. Either way the membership starts active. The new member is notified (live mode only, best-effort): an email when email is supplied, an SMS when phone is supplied, both when both — informational only, no activation step (login stays passwordless: magic link / OTP). Re-adding someone: if the person is currently SUSPENDED on this business (a dashboard action — not reachable via this API), the create REACTIVATES that existing membership (same technician id, their existing group; also notified). A technician REMOVED with deleteTechnician is a closed membership: re-adding the same email/phone links the SAME underlying person (no duplicate identity) but creates a FRESH membership with a NEW id — history stays under the old one. Owner/Administrator groups cannot be assigned via API key, and not at all in sandbox mode.

Optional relations (all validated; any missing id → 404 TECHNICIAN_NOT_FOUND with missing_ids): buddy_ids sets this technician's buddy list (use when creating a lead); lead_ids adds this technician as a buddy of each named lead (use when creating a buddy — the buddy-side way to attach the same lead↔buddy relation); service_area_ids assigns the technician to those service areas.

start_location_type=office snapshots the business address + coordinates into the technician at create time; address, start_location_lat, start_location_long in the body are ignored. Requires the business to have coordinates set (else 400 BUSINESS_LOCATION_MISSING). start_location_type=home (or empty) uses the address + coordinates from the body.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
emailNoEmail address. At least one of phone/email is required (identity resolution key).
phoneNoPhone number in E.164 international format: a leading `+` and the country code, e.g. `+16135550188`. A bare national number (`6135550188`) is REJECTED with PHONE_INVALID — there is no default region to guess the country from. At least one of phone/email is required (identity resolution key).
addressNoHome address (the day-start point when start_location_type=home).
lead_idsNoLeads this technician is a buddy of (set when creating a buddy; the technician is appended to each lead's buddy list). Optional; max 50 technician ids.
buddy_idsNoBuddies of this technician (set when creating a lead). Optional; max 50 technician ids.
full_nameYesThe person's full display name. Required; max 255 chars.
job_titleNoDisplay title (e.g. "Senior HVAC Technician").
join_dateNoFirst working day (YYYY-MM-DD).
assignment_tierNoCrew tier the matching engine assigns by: lead (can head a job), buddy (crew helper), float (excluded from auto crew-assign).
idempotency_keyNoUnique key making retries safe: a repeat send with the same key replays the original response (header Idempotent-Replayed: true) instead of re-running the operation. Reusing a key with a different body returns 422 IDEMPOTENCY_KEY_REUSE. (sent as the Idempotency-Key header)
service_area_idsNoService areas to assign the technician to. Optional; max 50. Discover via GET /service-areas.
business_group_idYesRole group for the new member. Discover IDs via GET /permission/groups (Owner/Administrator groups are rejected in sandbox mode).
start_location_latNoExplicit day-start latitude in decimal degrees (-90..90); when set it wins over the address geocode.
start_location_longNoExplicit day-start longitude in decimal degrees (-180..180); when set it wins over the address geocode.
start_location_typeNoWhere the technician starts their day: home (their address) or office (the business location). Drives the engine's travel estimates.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.1
    • changedInput schema / properties / phone / description
      Previous value: -"At least one of phone/email is required (identity resolution key)."New value: +"Phone number in E.164 international format: a leading `+` and the country\ncode, e.g. `+16135550188`. A bare national number (`6135550188`) is\nREJECTED with PHONE_INVALID — there is no default region to guess the\ncountry from. At least one of phone/email is required (identity resolution key)."
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only provide basic flags, so the description carries the full burden and does so richly: best-effort notifications, no activation step, reactivation vs new-membership semantics, group restrictions, and start-location precedence with the 400 BusinessLocationMissing condition. This is far more transparent than the annotations alone.

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

Conciseness5/5

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

The description is long but organized by lifecycle behavior, relation parameters, and start-location rules. Each section earns its place and adds non-obvious detail; there is no filler, repetition of the schema, or vague prose.

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

Completeness4/5

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

The invocation-side guidance is exceptionally complete: lifecycle, identity linking, notifications, group restrictions, relations, and location edge cases are all covered. The only notable gap is that the return/payload semantics are not described, and with no output schema present the description could have stated what the successful response contains.

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

Parameters5/5

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

Even with 100% schema coverage, the description adds crucial meaning: it explains that buddy_ids and lead_ids form the same relation from opposite sides, that phone/email act as identity-resolution keys, and that address/lat/long are ignored when start_location_type=office. This materially helps an agent choose correct parameter combinations.

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

Purpose5/5

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

The description opens with 'Creates a technician membership under the current business,' giving a specific verb, resource, and scope. It also distinguishes membership creation from the related update/delete and customer-creation tools, so an agent can tell exactly what this operation accomplishes.

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?

The description gives strong contextual guidance: it explains identity linking, reactivation of suspended memberships, fresh membership creation after deleteTechnician, and actions that are not reachable via this API. It names deleteTechnician and points to lookup endpoints for group/service-area IDs, though it does not explicitly name updateTechnician as the alternative for modifying an existing technician.

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

Deploy Server

Other Tools