Vibeleaderboard
← Course overviewModule 05 · Connect and create tools · Beta
Lesson 5.3

Module contents

Connect and create tools

Lesson 3 of 5

What does the table look like to a program?

A person reads the supplier table as a grid. A program reads it as fields with names, and a tool returns them the same way. This lesson introduces fields, identifiers and schemas using the table from lesson 1, then walks through three things that go wrong when the organizer asks for a supplier: a name that matches twice, a file that is not there, and a request whose answer never arrives. Each failure teaches one property a well-designed tool needs.

Numbered links identify sources. Underlined terms offer a definition without leaving the lesson.

Fields, identifiers and a schema

Here is the table again, with the first two lines labelled the way a program treats them:

id,name,category,contact,approved_on,notes          <- the header: six field names
S-002,Hedgerow Fencing,fencing,office@hedgerow.example,2025-03-14,   <- one record: six values

A is one named piece of a record: name is a field, and “Hedgerow Fencing” is its value in this record. A record is one supplier's set of values, one per field. The commas separate the values, which is why this file layout is called comma-separated values, or CSV. In the simple case shown, a program can split each line at its commas and pair the pieces with the header's names, so that a value can be asked for by its name rather than by counting columns. The simple case is not the general one. A value may itself contain a comma, or a line break, and the layout handles that by wrapping the value in quotation marks; a note reading “supplies hedging, bare-root” would be written "supplies hedging, bare-root". Splitting at every comma would then break one value into two. Programs use a CSV reader, a component that understands the quoting, and module 7 uses one when reading its quote-comparison file. The .csv at the end of the file name is a label that people and programs use to guess the format; it is not proof that the contents follow it. The last field, notes, is empty for four suppliers, which is why those lines end in a comma with nothing after it.

One field does a job the others cannot. An is a value chosen to name exactly one record within a stated system: S-003 names one supplier in the committee's table. The committee has chosen never to reuse a code once assigned, which is a useful design choice for this table and not part of what makes a value an identifier; other systems reuse or change theirs, and a field such as the contact address can also identify a record if it is unique in the table. A name cannot do the job here, because names repeat: two records contain the word Parkside. Lesson 1's API route returned identifiers with each row. Anthropic's engineering account of designing tools, written by Ken Aizawa in September 2025, makes the related point that technical identifiers are noise in a result meant only for reading but should be kept whenever a later operation will need to name the record again. 9 A row returned without any identifying value has to be found again before it can be updated, matched or deleted, and a second search by name may find something else.

The bracketed response in lesson 1 uses JSON, a text format for exchanging structured data. An object groups named values between braces, such as {"name": "Hedgerow Fencing", "approved": true}. Here name holds text and approved holds a true-or-false value. Square brackets enclose a list, so several supplier objects can travel together. The spelling and punctuation let software distinguish these parts; they do not establish that the values are accurate. 7

A is a written description of a data format: which fields exist, what kind of value each holds, and which are required. JSON Schema, one published way of writing such descriptions, uses exactly those elements: named properties, a type for each, and a list of the ones that must be present. 7 Here is the supplier table's schema written in plain words, as this course will use the idea:

record: approved supplier
  id           text, required, unique; pattern S- followed by three digits
  name         text, required
  category     text, required; one of fencing, plants, timber, tools, other
  contact      text, required; an email address
  approved_on  date, required; year-month-day
  notes        text, optional

A schema lets software check a record's shape before using it: a missing contact, a category outside the list, an approved_on that is not a date. That is a real check and a limited one. It confirms that a value has the expected form. It cannot confirm that Hedgerow's email address still works or that the committee still approves of them; those are questions about the world, and the file is the only witness. The JSON Schema guide draws the same line, describing what a schema validates as the structure of the data. 7 Module 1's habit applies: a check establishes what it checked.

The tool's results carry the same shape. In lesson 1 the MCP exchange returned rows as labelled values, and the API route returned them in brackets with each field named. That labelled form is what a harness can hand to the model without the model having to guess which column is which, and it is what a program can read without a person. A tool that returns a paragraph of prose instead forces the next step to parse sentences; a tool that returns fields lets the next step name what it wants.

An ambiguous name

The organizer's brief for a hedging job says to check that the supplier, Parkside, is approved. The model calls the tool with that name; under lesson 1's rule, any row whose name contains “Parkside” matches. Here is an authored result from a tool designed for this case, followed by one from a tool that was not:

find_supplier  name="Parkside"

well-designed result:
  matches: 2   (complete: every matching row is shown)
  [ {id: S-003, name: Parkside Fencing,   category: fencing, ..., source: approved-suppliers.csv row 4},
    {id: S-004, name: Parkside Nurseries, category: plants,  ..., source: approved-suppliers.csv row 5} ]

poorly-designed result:
  Parkside Fencing is an approved fencing supplier (quotes@parkside-fencing.example).

The second tool found the same two rows and returned the first. Nothing in its result says a second match existed, so the model, the skill from lesson 2 and the organizer all proceed with a fencing supplier for a hedging job. The operation succeeded and the result misled, which is module 2's pattern again: the request said “Parkside,” and the program decided that meant the first row.

The well-designed result does three things. It returns every match and says the list is complete, so that choosing is left to whoever can choose; a tool that cannot return everything, because there are thousands of matches, should instead say how many it returned and that more exist, so that incompleteness is disclosed rather than hidden. It returns identifiers, so that the choice can be recorded as S-004 rather than as a name that will match twice again next time. And it returns a source location, the file and row, so that a person can open the table and see the record the tool saw. A source location is one way of checking an observation, and a convenient one; without it, the check takes another route, such as running the search again or opening the original table, and those routes remain available. What the source location adds is a check that anyone reading the record can do at once.

A missing file

Now the committee has moved the table and nobody updated the harness's configuration. The tool looks for the file where it was and finds nothing:

find_supplier  name="Hedgerow Fencing"

result:
  error: file not found: Documents/Garden/Suppliers/approved-suppliers.csv
  (no rows were read)

Compare that with a tool that returns matches: 0 in the same situation. Both are accurate about something. The second is accurate about how many rows the tool returned and silent about why, and “no rows” reads as “no match,” and from there, unless the skill's step 2 intervenes, as “not an approved supplier,” which is a claim about Hedgerow that nothing supports. Module 3's swimming-club record had exactly this failure: a file-not-found result turned into a conclusion about the world. A tool that keeps errors separate from results, as the command-line guide recommends by sending them to a different output and signalling failure through the exit code, makes that confusion harder. 5 The error above names the path, which tells the model, and the person, where the tool looked, and it says that no rows were read, which stops the empty result being mistaken for an empty table. Aizawa's account adds that an error message should tell the caller what to do about it rather than returning an internal code, because the model will act on whatever it is given. 9

Eric Zakariasson, who writes about building command-line programs for agents, makes a related recommendation that the site's Intel collection summarizes: return the values a following step needs, such as an identifier or an address, rather than a sentence celebrating success, because an agent chains commands and each output feeds the next. 6 Read that as one practitioner's design advice. The reason it fits here is that an error is also an output the next step reads, and “something went wrong” feeds nothing.

A lost response, and which retries are safe

The third failure is the one module 2 left open. The harness sends the lookup to the supplier server and no response arrives within the time allowed. Module 3's trace showed this for a web fetch and allowed one retry. Whether a retry is safe depends on what the operation does, and this lesson can now say why in the tool's own terms.

find_supplier reads. Running it twice reads the file twice and changes nothing in the table. An operation with that property, that doing it again has the same intended effect as doing it once, is . Idempotent does not mean the response is identical: if the committee edited the table between the two attempts, the second read returns the changed rows, and that is correct, because the intended effect was to read what is there. Nor does it mean the repeat is free or unconditional. Module 3 noted that repeated reads consume time and, on a paid service, requests; a service may limit how often a caller may ask; and the second attempt has to be authorized like the first. What the property rules out is the specific harm of a duplicate: a second read cannot create a second record.

Now suppose the committee's service also offers add_supplier, and the harness sends a request to add Millbrook Timber and the response is lost. The server may have added the record and the reply vanished, or the request may never have arrived. Send it again and the table may contain Millbrook twice. Amazon's engineering account of this problem describes one standard remedy: the caller includes an identifier for the request itself, chosen once and reused on every retry, and the server records that identifier together with the change so that a repeat of the same request is recognized and not performed again. The account stresses that recording the identifier and making the change have to succeed or fail together, and that the server keeps such records for a limited time. 8 It is one design among several: a service may detect duplicates from the record’s contents. A status query can separately help resolve what happened, but does not itself make an operation idempotent. An absent row is inconclusive while the original request could still be pending; stop if its outcome cannot be resolved safely. Two consequences follow for the caller whichever design is used. First, the protection exists only if the server implements it; a caller cannot make an operation safe to repeat by being careful. Second, the protection covers what the design says it covers: a retry with a different request identifier is a new request, and a repeat after the server has forgotten the first is one too.

The practical rule for reading a tool's description is therefore a question, not a guarantee: for each operation that changes something, how does the service recognize a repeated request, and what must the caller do for it to? The command-line guide's dry-run flag answers a neighbouring question: a describes the changes an operation would make without making them, so that a person can inspect the plan before the effect. 5 A preview is only as good as its implementation, and it describes the state at the time of the preview; if the table changes between the preview and the action, the action may differ from what was shown. Still, a tool that offers one lets module 3's approval prompt show the proposed change; one that does not leaves the prompt showing only the request.

Four properties to look for in any tool

The three failures give four properties, and each is something you can look for in a tool's description or test with one call, without knowing how the tool is built.

Predictable format: results arrive as named fields, including identifiers and, where it helps checking, the source. Disclosed completeness: a search returns everything that matched and says so, or says how many it returned and that more exist, so that choosing is visible and nothing is silently dropped. Distinguishable errors: a failure says what failed and where it looked, apart from the results, and an empty result is not the same message as a failed read. Safe repetition, stated: reads can be repeated, within the service's limits; for operations that change something, the description says whether a repeat is recognized and how, and whether a preview exists.

These are not universal rules about software. They are what the supplier example needed, and other tools weigh them differently. A tool that sends a message previews it by showing the message, and also the recipients, the attachments and the account it will send from, which is a preview of a different kind from a table change. A tool that returns thousands of rows needs a way to return fewer, which the next lesson takes up. What transfers is the habit of reading a tool's results and errors as data the next step will act on, and asking whether that data is enough to act on correctly.

Carry this forward

  • A record is a set of named fields. Simple CSV lines split at commas; quoted values can contain commas and line breaks, so programs use a CSV reader, and a file's extension is a label rather than proof of its format. A schema describes the required shape of a record and checks form, not truth.
  • An identifier names one record within a stated system, and results that a later operation will use should keep one. Never reusing codes is this table's design choice, not the definition of an identifier.
  • A search should return every match, or disclose that it did not, with identifiers and a source location where they help checking. Returning the first of two matches is a completed operation that misleads.
  • An error should say what failed and where the tool looked, separately from results. A successful search with no matches and a failed read support different conclusions.
  • A read can be repeated after a lost response and may return changed rows; idempotent means the same intended effect, not the same response, and repeats still cost, are limited and need authorization. Whether a change can be repeated depends on how the server recognizes a repeat; a dry run shows a change as of the time it was previewed.

Lesson check

A fictional find_supplier tool returns matches: 0 both when no name contains the given text and when the table file cannot be opened. The model calls it for Hedgerow Fencing, gets matches: 0, and reports that Hedgerow is not approved. What does this lesson say about that report?

Choose an answer for each question.

This is a practice check. Answers reset when you leave this page. Results are not saved and do not place you in another module or award a qualification.

The tool now returns rows the model can act on. Sometimes it returns far more than the task needs. The next lesson asks whether every row has to pass through the model at all.

Sources · Reviewed 2026-09-29
  1. 9. Anthropic engineering (Ken Aizawa, 11 September 2025): Writing effective tools for agents, with agents
  2. 7. JSON Schema: Creating your first schema
  3. 5. Command Line Interface Guidelines (Prasad, Firshman, Tashian, Parish)
  4. 6. VibeLeaderboard Intel: Building CLIs for AI agents (Eric Zakariasson)
  5. 8. Amazon Builders' Library: Making retries safe with idempotent APIs

Sources support nearby explanations. Product details can change. Scenarios and model results are authored illustrations unless a lesson explicitly identifies a recorded execution. Module 7 identifies its offline code checks.