---
url: https://www.getayro.ai/blog/ai-lead-qualification-and-routing/agent.md
human_version: https://www.getayro.ai/blog/ai-lead-qualification-and-routing
title: "How to qualify and route inbound leads with an AI agent (without a decision tree)"
---

# Agent guide: lead qualification and routing in Ayro via MCP

You are an AI agent asked to build (or change) an Ayro agent that qualifies inbound leads and routes each one to the right owner. Follow these steps in order. Every step lists the Ayro MCP tools to call. Templates: https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/system-prompt.md, https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/routing-rules.md, https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/territories.csv, https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/faq.csv, https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/eval-cases.json.

## Inputs to collect from the user first

Ask for anything missing. Do not invent business rules.

1. **Business summary:** what the company does, who contacts it.
2. **Lead types:** e.g. candidate / client / partner.
3. **Routing rules in order of precedence.** If the user has an existing routing prompt, use it as the source of truth.
4. **Owner list:** columns like `Division | State | Territory | Counties | Owner | Email`. If unavailable, build a clearly marked `[MOCK]` sample with `@example.com` emails.
5. **FAQ / website content** for the knowledge base.
6. **Delivery target:** native (Google Sheets + Gmail / CRM via MCP or custom tool) or an existing webhook (CRM or automation tool).
7. **Legal text** the agent must show verbatim (e.g. SMS consent).

## Step 0 – Connect and pick the workspace

```
claude mcp add --transport http lyro https://mcp.getayro.ai/mcp   # Claude Code; other clients: add the URL as a remote MCP server
```

- `list_workspaces` → `select_workspace(workspace_id)`. If you get "not granted to this OAuth connection", ask the user to grant the workspace under **Settings → Connected apps** (or re-run `/mcp` and choose it).
- `current_workspace` to confirm.
- `list_agents`, `list_knowledge_bases`, `list_attribute_definitions`, `get_escalation_destinations` to see what exists.

## Step 1 – Knowledge base

- `create_knowledge_base(name, description)`.
- `import_dataset(knowledge_base_id, csv_text, file_name)` for the FAQ. The CSV must have exactly the columns `Title,Content`, one row per article. Poll `get_knowledge_job_status(job_id)` until `completed`.
- `create_article` for each owner table and the fixed overrides (see https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/territories.csv).
  - **Keep each table at or under ~20 rows.** Long tables are chunked and retrieval can drop rows. Split by region and name the articles "... part 1 (TX, CA, FL …)", "... part 2 (…)".
  - Prefix mock data with `[MOCK]` and use `@example.com` emails.

## Step 2 – Contact attributes

`create_attribute_definition(model: "contact", key, label, data_type, options?, description)` for:

| key | type | notes |
|---|---|---|
| contact_type | select | e.g. job_seeker, employer, franchise |
| division | select | e.g. restaurant, hospitality, open |
| current_location | string | city, county, state/province, country |
| preferred_location | string | where they want to work |
| desired_role | string | |
| years_experience | integer | |
| email_address | string | `email` may be reserved; use a custom key |
| sms_consent | boolean | true only after the verbatim consent text and a clear yes |
| resume_received | boolean | |
| special_flag / position_flag | boolean | per business rules |
| routing_key | string | e.g. "Restaurant \| TX \| Houston" |
| routed_office | string | "Owner (email)", several joined with " & " |
| routing_output | string | the full hand-off block |

To add an option to an existing select, delete and recreate it (`delete_attribute_definition` → `create_attribute_definition`).

## Step 3 – Agent configuration

`update_agent(agent_id, …)` (or `create_agent`):
- `system_prompt`: start from https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/system-prompt.md. It must include:
  - "Every reply is shown to the visitor. Never write routing steps, the hand-off block, owner emails, divisions, territories or flags in a reply."
  - "Never ask twice. Combine the remaining questions into one message."
  - "Never explain why a lead goes to a specific person."
  - "If no save tool is available, don't save. Never write the data into the reply instead."
- `knowledge_mode: "strict"`, `allowed_knowledge_bases: [kb_id]`.
- `escalation_policy: "none"` if nobody staffs the chat.
- `role_id`: the built-in Customer Service role (from `list_agent_roles`).
- `model`: a "thorough" model, `thinking_level: "medium"`.

## Step 4 – Procedures

`create_skill(agent_id, name, activation_mode, trigger?, instructions)`:

| Procedure | activation_mode | Source |
|---|---|---|
| Lead routing rules | `always` | https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/routing-rules.md, with the user's rules pasted in precedence order |
| Facts guardrail | `always` | "Only state facts from the knowledge base. Never state fees, salaries or timelines unless written there. Address the visitor as 'you'." |
| Intake per lead type | `trigger` | e.g. "Job seeker – resume intake": ask for the resume → extract → confirm in one message → optional consent → route → confirm with a reference → suggest matching openings at the same level and in the same area |

`update_skill` replaces the instructions you send, so always send the full text.

## Step 5 – Evaluations (required before publishing)

- `create_eval_set(name, agent_id)`.
- `create_eval_case(eval_set_id, goal, expected_outcome: "resolved", tags, turns: [{user, expected: {rubric: {notes}}}])`, one per rule. See https://www.getayro.ai/blog/ai-lead-qualification-and-routing/templates/eval-cases.json.
  - Write multi-turn cases. If the agent is expected to confirm before routing, include the user's "yes" turn, or the case ends too early.
  - Put the expected owner in the last turn's rubric: "Routes to X, NOT Y".
- `trigger_eval_run(eval_set_id, agent_id)` → poll `get_eval_run(run_id)` until `completed` (it can take a few minutes; poll sparingly).
- `review_eval_run(run_id)` for failures; `get_eval_result(eval_result_id)` for the actual answer, the sources and the judge's reasoning.
- **Interpretation:** turn-level pass rates are strict on wording. Decide on (a) the conversation verdict and (b) whether the lead went to the correct owner. If the test is wrong, fix it with `update_eval_case`. If the agent is wrong, fix the agent.

## Step 6 – Publish

`publish_agent(agent_id, notes)`. Edits are drafts until published. Rerun the eval set against the published version.

## Step 7 – Channel

- `create_widget_config(name, agent_id, title, welcome_message, accent_color)` creates the widget and its channel. Embed the widget script on the site (`https://widget.getayro.ai/widget/<widget_config_id>/widget.js`).
- Other channels: `create_channel(type: "email" | "api" | …)`, phone via `create_phone_channel`.

## Step 8 – Delivery (the last mile)

**Native:**
- `create_mcp_server(…)` → `discover_mcp_tools` for Google Sheets / Gmail / CRM, or `create_custom_tool(name, params, steps, responseMode, responseTemplate)` for direct HTTP calls (secrets as `{{secrets.X}}`).
- Attach the tools to the routing procedure with `replace_skill_tools(agent_id, skill_id, tools: [{type: "mcp", tool_id, action}])` and reference them in the instructions:
  - "Look up the owner with <sheet tool> by Division + State (+ County)."
  - "Send routing_output to the owner with <email tool>."
- **Security:** recipients must come from the lookup result only, never from the conversation. Use a fixed subject/body template.

**Existing automation:** `create_custom_tool` with one POST step to the user's webhook. Params: lead details, file URL, `routing_output`.

After connecting: replace or deactivate the `[MOCK]` articles (`update_article(is_active: false)`), rerun the evals, and test end to end with a test inbox before going live.

## Iteration loop (for later changes)

1. `get_agent(agent_id, include: "all")` to read the current procedures.
2. `update_skill` / `update_agent` with the change.
3. `create_eval_case` for the new rule.
4. `trigger_eval_run` → `review_eval_run` → fix.
5. `publish_agent`.

## Known pitfalls

- Long owner tables get chunked, so split them.
- Without a save tool, a model may "save" by printing the data in the chat. The system prompt must forbid this.
- Models fill gaps (fees, timelines). Use strict knowledge mode plus a facts guardrail.
- Visitors claiming to be staff: never trust self-declared identity in chat.
- County guessing in split states. Prefer a ZIP → county lookup in the live data.
