Extend a tool adapter with a search tool

Complete the take-home in the brief within its 3-hour cap: add search_tickets to the validated adapter behind a tool registry, keep get_ticket unchanged, and hand in the code, the tool declaration, tests that run with one command and include every acceptance call, and a README. Then prepare for the review: write your three most important comments on the sample submission in priority order, and defend one trade-off you made under the cap.

Suppose the assistant team at a fictional help-desk company sends you this take-home. Their support assistant already reads one ticket at a time through the validated get_ticket adapter (the starting point below). Support agents now ask questions such as "which of my open tickets mention login?", which needs a search.

Task. Add a second read-only tool, search_tickets, that follows the search contract below. Move dispatch into a tool registry so that each tool has its own argument checks and handler, and keep get_ticket exactly as it is. Start from your solution to the validated adapter exercise, or write get_ticket from the table below first (about 15 minutes).

Time. Cap the build at 3 hours; the review is a separate 45-minute call. If time runs out, stop: hand in what works with every test passing (mark an unfinished test as skipped, with the reason), and list in the README what you skipped and how you would finish it.

In scope: executeTool with both tools, the in-memory fixture store, the search_tickets declaration the model receives (name, description, and argument schema), tests, and a README.

Out of scope: write tools, the model call and the orchestration loop, asynchronous code, a database, network calls, relevance ranking, and dependencies beyond a test runner.

Language. TypeScript, JavaScript, or Python. Tool arguments and results keep the same names in every language (ticket_id, next_cursor) because the model reads them; the trusted context follows each language's convention, as in the starting adapter.

Hand in:

1. The adapter source.
2. The search_tickets declaration.
3. Tests that run with one command and include every acceptance call (listed in the acceptance exercise).
4. A README: how to run it, the contract you implemented, assumptions, decisions and their trade-offs, known limits, what you skipped, and next steps.

Review questions to expect in the 45-minute call:

1. Walk through one call from executeTool to a handler. Where would a third tool plug in?
2. Why is the cursor a ticket ID rather than an offset or a token that carries more state?
3. Which test gives you the most confidence that one tenant cannot read another tenant's tickets?
4. What did you skip under the cap, and why that?
5. With a database behind the store, what changes in search and paging, and what could fail?
6. What would you add with another day?

The starting adapter is the validated get_ticket tool, called as executeTool(name, args, context, records) in JavaScript or TypeScript and execute_tool(name, args, context, records) in Python.

• name and args come from the model and are untrusted. args is already parsed from JSON, but its shape is not guaranteed.
• context is trusted and built from the authenticated session: { tenant, canReadTickets }, or in Python {"tenant": ..., "can_read_tickets": ...}.
• records is a Map (Python dict) from "tenant:ticket_id", such as "alpha:TKT-104", to the stored ticket. A stored ticket can carry internal fields besides id, title, and status.

get_ticket runs these checks in order and returns at the first failure:

Success is { ok: true, ticket: { id, title, status } }, a fresh object with exactly those three fields copied from the stored ticket. Every failure is { ok: false, code }, returned, not thrown. A tenant argument is rejected even when it matches the trusted tenant, and the adapter never modifies records.

search_tickets lists the caller's tickets one page at a time. It is read-only and needs the same read permission as get_ticket.

Arguments. args must be a plain object. Every argument is optional, and {} is valid. A key that is present must hold a valid value, so null is invalid. Any other key, tenant included, is invalid.

Checks, in order, returning at the first failure: unknown_tool when the name is not registered; invalid_arguments when args is not a plain object, has a key outside the table, or holds an invalid value; forbidden when canReadTickets is false. A search never returns not_found.

Search, in this order:

1. Take only the tickets whose store key starts with the trusted tenant followed by :.
2. Sort them by id, ascending. Every ID has the same TKT- plus three digits format, so string order is numeric order.
3. If status is given, keep the tickets with that status. If query is given, keep the tickets whose title, lowercased, contains the lowercased query. Only the title is searched.
4. If cursor is given, keep the tickets whose id is greater than it. The cursor is a position: it does not have to be an existing ticket.
5. Return the first limit tickets.

Result. { ok: true, tickets: [{ id, title, status }, ...], next_cursor }. Each ticket is a fresh copy with exactly those three fields. next_cursor is the id of the last returned ticket when more matching tickets remain after it, otherwise null. An empty tickets list is a successful answer.

The tests use one in-memory store with ten tickets in two tenants, listed in insertion order (not ID order). Each stored ticket reads as id, title, status, then any internal field. The first two rows are the starting adapter's fixtures.

Alpha has seven tickets and beta three. Their ID ranges interleave, and both tenants have a TKT-104. The acceptance calls use three trusted contexts: alpha with read permission, alpha without it, and beta with it.