hail

Official

by hail-hq

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Create an agent

create_agent

Save an agent. Then call route_number so a number answers with it, or pass its id as agent_id to place_call.

Instructions

Save an agent. Then call route_number so a number answers with it, or pass its id as agent_id to place_call.

    ``system_prompt`` is what the agent follows. ``first_message`` is
    spoken after the AI line; omit it to let the caller speak first.
    ``ai_disclosure_line`` replaces the workspace AI line for this
    agent; ``{org}`` becomes the organization name. ``language`` is a
    lowercase ISO 639-1 code. ``max_duration_seconds`` is 60..3600.
    ``handover_max_duration_seconds`` (60..3600, default 1800) is the
    call limit once a handover contact answers.
    ``handover_contacts``: People the agent may hand a live call to:
    ``[{contact_id, note}]`` (max 10; ``note`` 1-200 chars says when to
    hand over). ``contact_id`` is an id from ``list_contacts``: a
    contact's uuid, or ``member:<user id>`` for a team member. The
    person needs a phone number. The agent never sees it.

    Returns the API's ``AgentResponse`` as a dict, or
    ``{"error": "<message>"}``.

Input Schema

Name	Required	Description	Default
`name`	Yes
`tools`	No
`language`	No
`voice_id`	No
`sms_enabled`	No
`ai_disclosure`	No
`first_message`	No
`system_prompt`	Yes
`voice_enabled`	No
`handover_contacts`	No
`recording_enabled`	No
`ai_disclosure_line`	No
`max_duration_seconds`	No
`handover_max_duration_seconds`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.29.0Oct 21, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Goes well beyond annotations by disclosing defaults and bounds (max_duration 60..3600, handover default 1800, max 10 contacts, note 1-200 chars), the {org} substitution in ai_disclosure_line, and the privacy behavior that the agent never sees the handover phone number. It omits permission requirements and what the boolean flags (sms_enabled, voice_enabled, recording_enabled) actually toggle.

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?

Front-loads the creation purpose and the follow-up routing before the parameter detail, so the most important information is first. The dense parameter block is long but each line carries distinct semantics; minor structural noise from the reStructuredText formatting.

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?

Output schema exists, so the return-value sentence is bonus rather than necessity, and the annotations already cover the safety profile. The main remaining gap is that seven of fourteen parameters, including the meaningful sms_enabled/voice_enabled/recording_enabled flags, have no semantics anywhere.

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 0% across 14 parameters, so the description carries the full burden and does explain roughly half: system_prompt, first_message (including what omitting it means), ai_disclosure_line, language, both duration fields, and handover_contacts structure. Name, tools, voice_id, sms_enabled, ai_disclosure, voice_enabled, and recording_enabled are left completely undefined.

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?

"Save an agent" plus the follow-up instructions ("so a number answers with it", "pass its id as agent_id to place_call") make clear this persists a new voice/SMS agent. The verb "Save" is slightly ambiguous versus the sibling update_agent, but the surrounding workflow removes most doubt.

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 explicitly states the next step after creation: call route_number or use the returned id with place_call, which gives an agent a concrete context for when this tool belongs in a sequence. It does not explicitly say when to prefer update_agent or delete_agent instead, so no true exclusion guidance.

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