> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jobmojito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Reusable patterns (skills) for driving JobMojito from AI assistants — the docs-first loop, merchant selection, safe writes, and reliable multi-step workflows.

JobMojito is built to be driven by **AI assistants**, not just humans. This section covers the reusable patterns — call them *skills* — that make automated hiring workflows reliable, whether you connect through the [MCP server](/mcp/overview) or call the [HTTP API](/how-the-api-works) from your own agent framework. It's tool-agnostic and complements the concrete [MCP tools reference](/mcp/tools).

## The core loop: understand → look up → act

Agents get into trouble when they call write actions speculatively. Structure the loop instead:

1. **Understand.** Before creating or changing anything, search the documentation (`search_documentation` over MCP, or these docs directly) to confirm the right endpoint and what each input means. Don't probe write tools to discover their schema.
2. **Look up.** Use the read-only **list** tools/endpoints (`list_interviews`, `list_candidates`, `list_interview_results`, …) to resolve names to ids and check current state before acting. Mind which id goes in which field — the same interview is called `interview_def_set_id`, `position_id`, or `interview_id` on different endpoints, and results need `interview_result_id`, not the row's `id`. See [Identifiers & admin links](/mcp/identifiers).
3. **Act.** Call the write action once you know the exact tool and inputs.
4. **Verify.** Read the result back (e.g. `get_interview_result_details`) rather than assuming success — especially for batch endpoints (see below).

## Pick the merchant first

Most actions are **merchant-scoped**. If the user manages more than one account, resolve the merchant *before* the first write:

* Over MCP, render the interactive `jobmojito_configuration` picker (or use `list_my_merchants` for non-UI clients), then pass the chosen `merchant_id` on every subsequent call. Omit it to act on the user's own account.
* Never guess a merchant. If it's ambiguous, ask the user.

## Follow cookbooks for multi-step work

Hiring flows are multi-step. Rather than chaining tools by trial and error, follow the published recipes:

* [Create an interview](/cookbooks/create-an-interview)
* [Invite candidates](/cookbooks/invite-candidates)
* [Pre-screen candidates](/cookbooks/pre-screen-candidates)
* [Review results](/cookbooks/review-results)
* [Manage a knowledge base](/cookbooks/manage-knowledge-base)

A typical flow: *create the interview → generate URLs / register candidates → review results → generate a report.*

## Handle batch endpoints per-row

`invite-users` and `register_users_for_interview` process each row independently and **always return HTTP 200** with a results array. A bad row doesn't fail the whole call — it carries its own error while the others succeed. Agents must inspect each row's `result` field, not just the HTTP status, and surface the failures back to the user. See [Batch endpoints](/how-the-api-works#batch-endpoints-return-per-row-results).

## Give the user clickable links

When a workflow produces something a person will want to open, present a Markdown link to the JobMojito admin rather than raw ids. Build the URL from the entity id using the documented [admin link patterns](/mcp/identifiers#admin-app-links-build-them-yourself), e.g. `https://app.jobmojito.com/interview_results/result/{id}`.

## Respect permissions and cost

* **Permissions.** Every call runs as the signed-in user (the token is forwarded), so the agent can only do what that user can. Treat `401`/`403` as "re-authorize or not permitted", not something to work around.
* **Credits.** Some actions consume account credits (creating interviews, running pre-screens, generating reports). For bulk or automated runs, make the cost visible to the user and confirm before large batches. See [How credits work](/how-credits-work).

## Safe-writes checklist

Before an agent performs a write, it should be able to answer:

* Which **merchant** am I acting as?
* Have I **read the docs / looked up ids** for this action?
* Is this **idempotent**, or will a retry double-charge or double-invite?
* For **batches**, will I inspect every row's `result`?
* Will I **report** links and per-row outcomes back to the user?

## Where to go next

* [MCP server](/mcp/overview) — connect an agent over MCP.
* [MCP tools reference](/mcp/tools) — the full tool inventory.
* [How the API works](/how-the-api-works) — base URL, errors, and the HTTP endpoint list for custom agents.