Tech World Software SchoolTWSS
0x30Lesson 4 of 8

Design tools and action contracts

Treat tools as an interface for the model: clear names and schemas, helpful errors, concise results.

22 min 6-question quiz 2 code exercises
By the end of this lesson you can
  • Design narrow tools with clear schemas and side-effect labels
  • Return errors the model can act on
  • Keep tool results concise with filtering and pagination

Tools are how a loop touches the world, and the model is their user. Anthropic calls this the agent-computer interface and suggests investing in it as much as in a human UI: clear names and descriptions, example usage, sensible parameters, and thorough testing (Building effective agents).

A good tool contract has:

  • One narrow purpose, with read-only and state-changing actions kept separate.
  • An input schema, validated by your code before anything runs.
  • Helpful errors: “priority must be one of low, medium, high (got ‘urgent’)” lets the model fix its call; “Invalid input” doesn’t.
  • Concise results: return what the next decision needs - filtered, paginated - not 5,000 lines that flood the context.
  • Safe repetition: timeouts, and idempotency for actions with side effects.

Try it

Up to 15 XP

Which tool design is better?

Each round compares two ways to expose the same capability to an agent.

Round 1 of 3: Let an agent look up customer ordersScore 0/0
tool_definition.py
1tool = {
2    "name": "list_orders",
3    "description": "Read-only. List a customer's orders, newest first.",
4    "input_schema": {"customer_id": "string", "limit": "integer <= 50"},
5}
6print(tool["name"], "-", tool["description"])
Output
list_orders - Read-only. List a customer's orders, newest first.

Key takeaways

  • Design tools for the model like a UI for a person: narrow, documented, tested.

  • Validate every argument and return errors that explain how to fix the call.

  • Return concise, paginated results; keep side-effecting tools separate and safe to retry.

Lesson quiz

6 questions · pass with 5 correct · up to 50 XP

Passing this quiz completes the lesson and keeps your streak going. Questions you miss come back in review sessions later.

Practice: write Python

Write Python in the editor and run it against sample inputs. Python runs locally in your browser using a WebAssembly runtime.

Exercise 1

Validate calls with helpful errors

+25 XP

Each line is a JSON call {"tool": ..., "arguments": {...}} checked against SCHEMAS (types str, int, or a list of allowed values). Print ok, or error: followed by every problem joined with ; , in this order:

  • unknown tool 'NAME' (available: A, B) (alone, if the tool doesn’t exist);
  • unknown argument 'NAME' for each extra argument (sorted);
  • missing argument 'NAME' (schema order);
  • NAME must be a string|an integer (got REPR) or NAME must be one of A, B, C (got REPR) (schema order; booleans are not integers).
  • Five calls
main.py
Loading editor…

Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.

Exercise 2

Paginate tool results

+25 XP

Line 1 is a JSON list of results. Line 2 is PAGE_SIZE CURSOR, where CURSOR is start or a number (the index to continue from). Print each result on the page, then showing A-B of N (1-based) and next_cursor: C or next_cursor: none.

  • First page
  • Last page
main.py
Loading editor…

Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.

Questions about this lesson

Stuck? Ask. Figured something out? Share it. Explaining is one of the best ways to learn.

Loading posts…