Skip to content
POLARISAI ACADEMY
R07-101 · Navigator

Tool Use, Function Calling, MCP and Workflow Automation

You can list the calls in a fixed workflow, reject arguments that fail a written schema, and count how many times stored state changes when the same idempotency key or the same webhook event id arrives again.

Level
Navigator
Time
24 h (estimate)
Prerequisites
F01–F07, R02-201
Course 1 of 4
Jump to

After this course you can

The student can build a compliant MCP server exposing typed, idempotent tools and an agent client that selects and executes the correct tool sequence across 30 frozen multi-step scenarios.

A fixed workflow and an agent loop

A deterministic workflow is a sequence written down before it runs. Ordinary code can run it, and so can a node editor. Each box names one tool, and the wires name the only order allowed. For a paid mug order this lesson uses four steps: lookup_price, then reserve_stock, then charge_card, then mark_paid. lookup_price only reads a price. reserve_stock and charge_card change stored state. mark_paid runs when a webhook arrives, an HTTP request an outside system sends to your receiver. With the same sku and the same quantity, those steps stay in that order. The host, the program that holds the chat and runs the tools, follows the list. A charge_card call while that order has no stored reserve returns the code out_of_order, moves 0 cents, and leaves the card untouched.

An agent loop asks the language model on every turn. The host sends the tool list and the results so far. The model returns one tool name and one arguments object, or it returns a final sentence and the loop ends. The host runs that single call, appends the result, and asks again. The model can repeat a read, skip a step, or name charge_card before reserve_stock. This lesson caps the loop at 8 tool calls. The 8th call still runs when the schema accepts it. A 9th call starts never. The host stops with the code step_cap. That cap is a rule of this lesson, so you can count it on paper. A fixed workflow and an agent loop can share the same four tools. The workflow's order sits in the graph. The loop's order is whatever the model emits, and the host checks it before each run.

The schema checked before the body

The host checks the arguments against a schema before the tool body runs. This lesson uses a small part of JSON Schema. The value must be an object. additionalProperties is false, so a key that the schema omits is rejected. required lists the keys that must appear. Each property has a type. For reserve_stock the properties are sku as a string, qty as an integer with minimum 1, and idempotency_key as a string, and all three are required. qty of 0 fails the minimum. A negative qty fails it. A qty written as a string fails the type, even when the characters look like a number. lookup_price requires only sku. charge_card requires order_id as a string, cents as an integer with minimum 1, and idempotency_key as a string. Walk the rules one key at a time. An accepted object may enter the body. A rejected call changes no stock and charges no card.

In the Model Context Protocol (MCP), the open protocol a chat app uses to reach tools, the server is what exposes that schema. The client asks with the method tools/list. Each tool in the result has a name, a description, and an inputSchema. This lesson's server lists four tools: lookup_price, reserve_stock, charge_card, and mark_paid. The client invokes one with tools/call. The params carry that name and an arguments object. The messages are JSON-RPC 2.0. A schema miss is a protocol error: the response has an error object, and the tool body runs zero times. The specification's sample for an unknown tool name is a JSON-RPC error with code -32602. A failure inside a tool that did run is a different shape. The response is a normal result, the field isError is true, and a content block holds text the model can read on the next turn. The specification tells a server to validate every tool input, and it says a person should be able to deny a call. This lesson's host validates the arguments, and it shows the cents and the key before a charge.

One key, one side effect

A side effect should land once when the same request is delivered twice. The caller supplies an idempotency key, a string it chose for that one intended change. The tool keeps a ledger from the key to the first stored result. The first accepted call with a new key applies the change and stores the result. A later call with the same key and the same arguments returns the stored result and applies the change zero more times. A later call with the same key and different arguments applies nothing and returns the code key_reused. A read such as lookup_price has no ledger entry. Running it twice leaves the stored numbers as they were, so a repeated read is safe even with no key. Reserve and charge are the calls that need a key, because each of them writes.

A webhook uses the same ledger idea with an event id. The receiver stores event_id after a successful handle. The first POST whose event_id is new may run mark_paid once. A second POST with that same event_id returns the stored acknowledgement and runs mark_paid zero more times. A different event_id is a new event and may run mark_paid once more. Count HTTP requests and state changes as two different totals. Two POSTs and one state change is a normal duplicate delivery. Three POSTs can still be two state changes when two of them share an id and the third id is new. The idempotency key and the event id are both strings you store. The key protects a call you send. The event id protects a call an outside system sends to you. A new key for a retry of a charge that might already have landed would open a second charge. Keep the key.

Structured errors and retries

When the tool body runs and the business step cannot finish, the tool returns a structured error the host can branch on. This lesson uses four fields: ok set to false, a code string, retryable set to true or false, and a short detail. The paper rule is small. If retryable is true and the number of attempts so far for that key is under 3, send the same arguments and the same key again. If that number is already 3, stop with the code retries_exhausted and send no fourth attempt. If retryable is false, stop at once. invalid_arguments is retryable false, and in this lesson that code means the body ran zero times. card_declined is retryable false. timeout is retryable true. step_cap is retryable false. out_of_order is retryable false. key_reused is retryable false.

A lost response is the case the ledger is for. The server may already have stored the success and charged the card, while the client only saw a timeout. The retry uses the same key. The ledger returns the stored success, so the card is charged once. Treat a timeout as unknown until the ledger answers. A fresh key after a timeout would ask for a second charge. In an agent loop the model sees the structured error as tool content with isError true, and the host still enforces the attempt rule. The model picks no fourth attempt, and it swaps no key after a timeout. The same branching works in a fixed workflow: the node that receives timeout either sends the identical call again or stops, using the rule above and no other.

An example

Order 17, counted by hand

Order 17 buys 2 units of sku MUG. lookup_price returns 450 cents for one unit. The line total is 2 × 450 = 900 cents. Stock of MUG starts at 10. The reserve call uses sku MUG, qty 2, and the idempotency key ord-17-reserve. Those arguments match the schema: the three required keys are present, qty is an integer of at least 1, and no extra key appears. The first call reserves 2 and stores the result. Stock left is 10 − 2 = 8. The network then delivers the same arguments again. The ledger finds ord-17-reserve, returns stock_left 8, and the stock stays 8. Reserve calls received: 2. Times the stock decreased: 1. The person has already confirmed a charge of 900 cents, the check the host shows before a sensitive tool runs.

charge_card uses the key ord-17-charge and cents 900. The server charges 900 cents and stores that result, then the response is lost. The client sees timeout. timeout is retryable, and the attempt count is 1, which is under 3, so the client sends the same key and the same 900 again. The ledger returns the stored success. The card shows one charge of 900 cents. A webhook then arrives with event_id evt-88, and the receiver runs mark_paid once. A second delivery of evt-88 returns the stored acknowledgement, and mark_paid stays at one run. Deliveries of evt-88: 2. Runs of mark_paid: 1. Separately, a reserve whose qty is the string 2 fails the integer check. The host records invalid_arguments, the body runs zero times, and that call leaves the stock unchanged. A charge_card with no reserve stored for the order returns out_of_order, and the card moves by 0 cents.

Exercise

Order 21 on paper

Order 21 buys sku BOWL at 325 cents each, quantity 4. Compute the line total in cents. Stock starts at 6. First take the arguments sku BOWL and qty 4 with no idempotency_key. Name the code, say whether the body runs, and write the stock after that attempt. Then accept a reserve with key ord-21-reserve and qty 4, and apply two further calls with that same key and that same qty. Write the stock and how many times the stock decreased. Then reuse ord-21-reserve with qty 3, and write the stock and the code. The charge server stores a success for the line total and the client sees a timeout, then the client retries that same key. Write how many charges hit the card, in cents. The webhook delivers evt-21 twice and evt-22 once. Write how many times mark_paid runs. For each of these four results, name the host action: card_declined, a timeout on attempt 1, invalid_arguments, and step_cap after 8 tool calls.

The line total is 325 × 4 = 1300 cents. The call with no key is invalid_arguments, the body runs zero times, and the stock stays 6. The accepted reserve leaves 6 − 4 = 2. The two retries return the stored result, the stock stays 2, and the stock decreased once. The qty 3 reuse returns key_reused and the stock stays 2. The card takes one charge of 1300 cents. evt-21 runs mark_paid once and the duplicate runs it zero more times, then evt-22 runs it once, so mark_paid runs 2 times across 3 deliveries. card_declined stops at once. The timeout on attempt 1 retries the same key, because 1 is under 3. invalid_arguments runs the body zero times. step_cap stops the loop, and a 9th call starts never.

Check questions

Answer on your own first. Then open a question to see the answer.

In order 17, one mug is 450 cents and the quantity is 2. What is the line total in cents, and what is stock_left after the retry of the key ord-17-reserve?

900 cents. stock_left is 8. The stock went from 10 to 8 on the first reserve, and the retry left it at 8.

A tools/call for reserve_stock sends qty as a string. Does the tool body run, and which lesson code does the host record?

The body runs zero times. The host records invalid_arguments. That miss is a protocol error, so the response has an error object rather than a tool result with isError.

For the key ord-17-charge the server stored a charge of 900 cents and the client saw a timeout. The client sends the same key and the same 900 again. How many charges are on the card?

One charge of 900 cents. The second call returns the stored result and applies the charge zero more times.

How many times does mark_paid run when evt-88 is delivered twice, and what does the host do when retryable is false?

mark_paid runs once. When retryable is false the host stops at once and sends that call no further time.

Take with you

State changes once when the schema accepts the arguments and the same idempotency key or event id returns the stored result on every later delivery. A fixed workflow writes the call order, and an agent loop still has to obey that schema, that key, and the cap of 3 attempts.

Final task

Submit an MCP server and client in Python or TypeScript that pass 30 fixed automated protocol, schema-validation, idempotency, and error-recovery tests against a deterministic model stub.

The final task is marked against fixed answer keys and automated tests once the tests open.

Terms in this course

This course has no terms of its own in the glossary yet. Terms from earlier courses are used here too.

More lessons coming

The first lesson is open to read. The rest of the course is being written, and tests and diplomas come later. Join the waitlist