conecto. Get started
Hiring

Write a skills test

hiring_save_assessment · Changes data · Markdown

Writes a skills test or changes one: questions scored on their own, written answers to mark, a time limit and shuffling.

$0.01 a call

From your agent’s balance. A call that fails costs nothing.

An example

Write a short skills test for mechanics: the torque for a carbon seatpost clamp, and how they'd find a creak that comes and goes.

Your agent callshiring_save_assessment$0.01 a call

The example business is Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. The reply is the one the tool really gives.

With these arguments
{
  "title": "Workshop basics",
  "time_limit_minutes": 20,
  "questions": [
    {
      "type": "choice",
      "prompt": "A carbon seatpost clamp is marked 5 Nm. How do you tighten it?",
      "options": [
        "To 5 Nm with a torque wrench",
        "Hand-tight, then a quarter turn",
        "To 8 Nm, to be safe"
      ],
      "correct": "To 5 Nm with a torque wrench",
      "points": 1
    },
    {
      "type": "long_text",
      "prompt": "A customer's bike creaks under load, but only some days. How would you find the cause?",
      "points": 5
    }
  ]
}
What comes back
{
  "assessment": {
    "assessment": "workshop-basics",
    "title": "Workshop basics",
    "intro": null,
    "time_limit_minutes": 20,
    "shuffle": false,
    "question_count": 2,
    "max_score": 6,
    "sent": 0,
    "completed": 0,
    "updated_at": "2026-10-14T08:00:00+00:00",
    "questions": [
      {
        "id": "q1",
        "type": "choice",
        "prompt": "A carbon seatpost clamp is marked 5 Nm. How do you tighten it?",
        "points": 1,
        "options": [
          {
            "id": "o1",
            "label": "To 5 Nm with a torque wrench"
          },
          {
            "id": "o2",
            "label": "Hand-tight, then a quarter turn"
          }
        ],
        "correct": [
          "o1"
        ]
      },
      {
        "id": "q2",
        "type": "long_text",
        "prompt": "A customer's bike creaks under load, but only some days. How would you find the cause?",
        "points": 5
      }
    ]
  }
}

Use it when

Candidates should show they can do the work before an interview.

What it does

Write a skills test for candidates, or change one (give its slug): questions with one or more right options are scored on their own; short answers too when you list the accepted ones; written answers wait for hiring_mark_assessment. Optional time limit and shuffling. Write tests about the job's real work; personality and IQ-style questions are not what this is for. Questions stay fixed once someone has started the test; save a new test instead.

What comes back

assessment: the test with its slug, title, questions, time limit and counts. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
assessmentstringThe test (its slug from hiring_list_assessments). 1 to 80 characters.
titlestring2 to 160 characters.
introstringMarkdown shown before they start. Up to 5,000 characters.
questionsarray of objects[{"type": "choice", "prompt": "...", "options": ["A", "B", "C"], "correct": "B", "points": 1}, {"type": "multi_choice", ..., "correct": ["A", "C"]}, {"type": "short_text", "prompt": "...", "accept": ["42"]}, {"type": "long_text", "prompt": "...", "points": 5}]. 1 to 50 items.
time_limit_minutesinteger0: none. 0 to 180.
shufflebooleanShuffle questions and options for each candidate.

The call

Over MCP, call hiring_save_assessment on https://api.conecto.chat/mcp/hiring. Over REST:

Terminal
curl -X POST https://api.conecto.chat/v1/tools/hiring_save_assessment \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Workshop basics","time_limit_minutes":20,"questions":[{"type":"choice","prompt":"A carbon seatpost clamp is marked 5 Nm. How do you tighten it?","options":["To 5 Nm with a torque wrench","Hand-tight, then a quarter turn","To 8 Nm, to be safe"],"correct":"To 5 Nm with a torque wrench","points":1},{"type":"long_text","prompt":"A customer'\''s bike creaks under load, but only some days. How would you find the cause?","points":5}]}'

When it refuses

A refused call costs nothing and says what to do next.

CodeWhenWhat to do
not_set_up404The business has no careers page yet.Run hiring_setup_careers first.
not_found404No skills test has that slug.Call hiring_list_assessments and use one of its slugs.
invalid_input400A new test has no title or questions, or a question is not in the right shape.Fix the question the message names.
in_use409Candidates have started the test, so its questions stay.Save a new test instead.

More Hiring tools

All 25 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md