Update a skill

JSON Schema for the values the agent COLLECTS from the caller during the conversation. MUST be a JSON Schema object of the form { "type": "object", "properties": { "<param_name>": { "type": "string|number|boolean", "description": "..." }, ... }, "required": ["<param_name>", ...] } — an object with a top-level "properties" map, NOT a bare/flat map of param->spec. Put ONLY caller-collected inputs here; operator settings (e.g. an email skill's to/subject/from_name) belong in executionConfig, never here.

Skill-type-specific operator settings (NOT the caller-collected values — those go in parametersSchema). Keys depend on skillType: email — { to: recipient email(s), comma-separated, REQUIRED, supports {param} templating e.g. "team@co.com" or "{customer_email}"; subject: REQUIRED, supports {param}; from_name: optional inbox display name (the address is always the verified no-reply@ sender, never set it here); intro: optional lead line; reply_to: optional, supports {param} e.g. "{customer_email}" }. http_webhook — { url (REQUIRED), method, headers, timeout_ms }. db_query — { sql_template }. transfer — { destination }. sms — { from: the messaging-enabled sending number in E.164 (OPTIONAL — leave it blank and the sending number is DERIVED at send time from the agent's SMS-active number, preferring the DID the call/chat arrived on); message: the body template, supports {param} }. The recipient is collected at call time as the "to" argument (the consent moment). An agent that owns an SMS-active number also gets a DERIVED send_sms tool automatically (no skill row needed) so it can OFFER TO TEXT the caller. builtin — { action: end_call|take_message|repeat }. geo — { action: check_service_area|find_nearest_location; for check_service_area: origin_address + radius_miles (is the caller within radius_miles of origin_address?); for find_nearest_location: roster = an array of { label, address, phone, lat?, lng? } locations to find the closest of (pre-geocode a large roster via POST /agents/{id}/geocode-roster so lat/lng are stored and routing is instant), plus optional route_by_caller_number:true to route from the caller's inbound-number area code (approximate — confirmed with the caller) when no address is given, plus optional radius_miles to gate coverage (each location covers that many miles, so the result carries in_service_area=false and the agent says it doesn't serve the area when the nearest location is farther) }. The LLM passes the caller's { address }. Geo is FREE to customers. Native-integration skills (calendar/google_sheets/shopify) are configured via the connect/provision flow, not here. playbook — NOT authored here. An enabled playbook is automatically a tool the agent can call; there is no skill row to create and no id to wire up (createSkill and updateSkill refuse skillType=playbook with 422 playbook_not_a_skill). Build playbooks with POST /agents/{agentId}/playbooks. allow_direct — a cross-type flag any skill may set: { "allow_direct": true }. A skill used as a STEP inside an enabled playbook is normally hidden from the agent's own tool list, so the agent cannot perform the playbook's steps piecemeal and skip the sequence the playbook guarantees. Set allow_direct:true on a skill that is legitimately BOTH a playbook step and a standalone capability (e.g. a lookup used inside "Book a visit" that callers also ask for on its own), and it stays directly callable as well.

Tool parameters the SERVER fills from verified call state instead of the agent — an object mapping a parameter name to a source, e.g. {"phone": "caller_number"}. The only source today is caller_number, the verified number the caller is calling from. A bound parameter is REMOVED from the tool the agent sees, so the agent never fills it, never asks the caller for it, and cannot get it wrong — the platform supplies the verified value when the tool runs. This applies wherever the tool runs, including when a playbook step calls it. Voice-only by nature. On channels with no caller id (chat, or a call with the number withheld) the parameter is sent ABSENT rather than blank or guessed, so your endpoint can apply its own required-field rules. Use it for identity fields you must be able to trust — the phone number a lookup keys on, or the recipient of a confirmation text. Omit or send {} to keep the historical behavior (the agent fills every parameter). An unknown source is rejected with 422 rather than ignored.