Schema and description

The model never sees a tool’s operation tree. It sees the name, the description and the json_schema, and those three decide whether the tool is called at the right moment with the right values. Write them as prompt, not as bookkeeping.

`name`

The function name the model is shown. It must match ^[a-zA-Z_][a-zA-Z0-9_]*$ and be unique in the workspace. Name the capability in snake_case: book_appointment, not post_booking_v2. These names are reserved for tools the platform injects, and creating or renaming a tool to one returns 400 '<name>' is reserved by the platform: voicemail_detected, submit_result, finish_without_result, get_faq_answers, lk_agents_cancel_task, lk_agents_get_running_tasks.

`description`

The description tells the model when to call the tool, and when not to. Name the conditions, the neighbouring tools it must not be confused with, and any cost the caller will feel.

Book a clinic appointment. Call this only after the caller has agreed to one
specific date and time — never to browse availability, which is what
find_appointment_slots is for. To move an existing booking, call
reschedule_appointment instead; calling this twice creates two bookings.

A tool with an empty description is shown to the model with only its name, and the dashboard’s tool list flags it.

`json_schema`

The arguments the model fills in, as a JSON Schema object.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "The appointment date as YYYY-MM-DD. Convert what the caller said ('next Tuesday') using today's date."
    },
    "time": {
      "type": "string",
      "description": "24-hour start time as HH:MM. Must be one of the slots find_appointment_slots returned."
    },
    "reason": {
      "type": "string",
      "enum": ["consultation", "follow_up", "vaccination", "test_results"],
      "description": "Why they are coming in. Ask if the caller has not said."
    },
    "notes": {
      "type": "string",
      "description": "Anything the clinician should know, in the caller's words. Omit if they mention nothing."
    }
  },
  "required": ["date", "time", "reason"]
}

Declare only values the caller can say or the agent can know. An internal UUID gets invented. Take the order number and look the id up in the tree.
Give every property a description: what goes in it, in what format, and how to get it from the conversation.
Require only what the tree cannot run without. The model invents a value for a required field rather than leave it out.
Use enum for closed sets, so gold, Gold and gold tier cannot all reach your API.
Never take a credential as an argument. Read it from {{secrets.NAME}}. Publish warns when an Authorization, X-Api-Key, Api-Key or Cookie header is built from {{args.…}}.

Changing the schema is a patch. Omitted fields are left alone; json_schema is replaced whole.

curl -X PATCH https://api.talqing.com/v1/tools/2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44 \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "json_schema": {
      "type": "object",
      "properties": {
        "date": { "type": "string", "description": "The appointment date as YYYY-MM-DD." },
        "time": { "type": "string", "description": "24-hour start time as HH:MM." }
      },
      "required": ["date", "time"]
    }
  }'

await talqing.tools.update({
  tool_id: "2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44",
  patchToolRequest: {
    json_schema: {
      type: "object",
      properties: {
        date: { type: "string", description: "The appointment date as YYYY-MM-DD." },
        time: { type: "string", description: "24-hour start time as HH:MM." },
      },
      required: ["date", "time"],
    },
  },
});

talqing.tools.update(
    "2b7d1f08-4c9a-4e6b-8f21-0d5a3c7e9b44",
    json_schema={
        "type": "object",
        "properties": {
            "date": {"type": "string", "description": "The appointment date as YYYY-MM-DD."},
            "time": {"type": "string", "description": "24-hour start time as HH:MM."},
        },
        "required": ["date", "time"],
    },
)

What schemas are accepted

The schema is checked as JSON Schema Draft 2020-12, and the whole vocabulary is accepted: enum, minimum, pattern, format, items, nested properties, $defs, anyOf.

Rule	Refusal
It must be a JSON object	`tool json_schema must be a JSON object`
It must be a valid Draft 2020-12 schema	`tool json_schema is invalid: <reason>`
It must describe an object of named parameters	`tool json_schema must describe an object of named parameters`

A schema with no top-level type is read as an object, so {"properties": {...}, "required": [...]} is accepted. {} means no arguments.

{{args.NAME}} is checked against the top-level properties only. {{args.address.city}} checks that address is declared.
The model’s arguments are validated against the schema before the tree runs. A call that does not match never reaches your endpoints: the tool fails with Tool arguments are invalid at <path>: <message>, which is what the model is handed.

The dashboard’s Arguments table holds a flat object of string, number, integer, boolean and enum properties, each with a description and a required flag, and a dashboard save rewrites json_schema from that table. Any richer schema written over the API — items, nested properties, minimum, pattern, format, default — is dropped by the next dashboard save.

The operation tree

What runs once the model has called the tool.

Templating and data

Reading {{args.…}} and moving values between operations.

Get started

Build

Guides

Schema and description

`name`

`description`

`json_schema`

What schemas are accepted

Next

The operation tree

Templating and data

​name

​description

​json_schema

​What schemas are accepted

​Next

The operation tree

Templating and data

`name`

`description`

`json_schema`

What schemas are accepted

Next