Creating Tools

In Module 3, I exposed the support-automation system's knowledge base and ticket history as MCP resources. The AI could read every KB article and browse recent tickets without any intervention from me. That was the right call, because reading carries no risk: if the AI reads the wrong article, nothing breaks. The KB is still intact. The ticket queue is undisturbed.

But classifying a ticket as high-severity, routing it to the payments queue, or paging an on-call engineer? Those are actions. They change state, notify people, and cannot be undone by reversing the call. They belong in tools, not resources.

In the support-automation system, I discovered this distinction the hard way. An early prototype exposed "route ticket" as a resource URI (tickets://route/{id}) just because it felt symmetric. The problem: AI clients read resources speculatively to understand what is available. The first time an AI listed available resources to orient itself, it silently routed three live tickets to the wrong queue. After that, routing became a tool — something the AI must deliberately invoke, not passively discover.

The line is simple:

• Resource: the AI reads without changing anything. KB articles, ticket lists, agent schedules.
• Tool: the AI triggers a state change. Assign a queue, send a notification, escalate a case.

Think of a tool like a power outlet. Plugging in triggers something real — a fan spins, a heater warms, a machine starts. Unplugging does not reverse what already happened; it just stops future current. MCP tools work the same way: calling escalate_ticket sends a page. There is no "un-escalate" endpoint on the pager system.

This analogy matters for design. Because tools have side effects, they need three things:

1. Clear input schemas — the AI must know exactly what parameters to supply before calling the tool.
2. Explicit error responses — if the tool cannot complete, it must say why, not silently succeed.
3. Idempotency awareness — decide upfront whether calling the tool twice is safe.

In the support-triage server, classify_ticket is idempotent: classifying the same ticket twice produces the same category. route_ticket is not: routing a ticket that is already routed could double-assign it.

The MCP TypeScript SDK provides ListToolsRequestSchema for the tool-listing handler. The AI calls this first, reads the schemas, then decides which tool to invoke. Notice the import: this is the typed schema form, not the string "tools/list".

The other two tools follow the identical shape. route_ticket takes { ticket_id, category } — where category comes from a prior classify_ticket call. escalate_ticket takes { ticket_id, reason } — a freeform explanation of why escalation is needed.

A note on tool descriptions: the text in description is what the AI reads to decide whether to call the tool. Write it as a verb clause ("Classify a support ticket...") that tells the AI what the tool does and when to use it. Vague descriptions produce unpredictable tool selection — the AI picks based on semantics, not on your intentions.

Mid-Module Checkpoint

Before writing the handlers, predict the answers to these:

• Which tool must the AI call first for a new ticket: classify_ticket or route_ticket? What happens if it calls them out of order?
• If escalate_ticket fails because the pager API is down, should the handler return isError: true or throw an uncaught exception? What is the difference from the AI's perspective?

Keep those answers in mind as you read each implementation below.

CallToolRequestSchema is the handler for tool invocations. The AI supplies the tool name and arguments; the handler dispatches on name, validates inputs, and runs the logic.

First, the classifier helper — a simple keyword-based function that maps ticket content to a category:

The classify function is intentionally simple — it uses keyword matching, which is fast but brittle. In a production support system, you would replace it with an embedding-based classifier or an LLM call that understands context ("my payment didn't go through" maps to billing even without the word "charge"). The MCP handler does not care which approach you use; it calls classify(content) and moves on.

Now the CallToolRequestSchema handler. The classify_ticket branch uses that helper and returns a JSON string the AI can parse for the next tool call:

Routing takes the category from classification and assigns the ticket to the right support queue. Add this branch inside the existing CallToolRequestSchema handler, before the final throw:

The ?? fallback handles unknown categories gracefully: if classify_ticket somehow returns a value not in queueMap, the ticket lands in tier-1-support rather than causing an unhandled error.

When the AI uses the full triage server, the typical call sequence looks like this: first classify_ticket runs on the incoming ticket text, then route_ticket takes the returned category and assigns the queue. Escalation is optional — it only happens when the AI (or a downstream rule) determines the situation is urgent enough to page a human.

Escalation is the highest-stakes tool in the server — it pages an on-call engineer, which has real cost and interruption impact. The handler must validate the reason before proceeding and return a structured error if escalation is not warranted.

Three patterns to note here. First, validate before acting: check the reason length before touching any external system. Second, isError: true: setting this flag signals failure to the AI so it can decide whether to retry, apologize to the user, or try a different approach. Third, catch external errors: any real pager API call belongs in try/catch, and the error surfaces as a structured response — never as an uncaught exception that crashes the handler.

The three tools above cover the core support-triage loop. In a production deployment, you would also add:

• Authentication: verify the MCP client has permission to call escalation tools before executing any state-changing logic.
• Rate limiting: prevent the AI from flooding the pager with escalations if it enters a retry loop.
• Audit logging: record every tool call with ticket ID, arguments, outcome, and timestamp for compliance and debugging.
• Idempotency keys: pass a unique key per tool call so retries do not create duplicate queue assignments or duplicate pages.

These patterns live outside the MCP protocol itself — they are server-side concerns implemented inside handler functions. MCP gives you the hooks; you supply the guardrails.

Extend the support-triage server with a summarize_ticket tool that formats a ticket into a structured summary for the routing dashboard.

Steps:

1. Add summarize_ticket to the ListToolsRequestSchema handler. Required inputs: ticket_id (string), content (string), category (string).
2. Add a summarize_ticket branch to the CallToolRequestSchema handler.
3. The summary field should be the first sentence of content (split on . or newline).
4. The priority field should be 'high' if content contains 'urgent' or 'critical' (case-insensitive), else 'normal'.
5. Return JSON.stringify of { ticket_id, category, summary, priority, generated_at }.

Worked Solution