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

Module contents

Connect and create tools

Lesson 5 of 5

What must a tool's contract say?

The module has looked at one operation from every side. This lesson writes it down. A tool contract states what a tool is for, what it takes, what it returns, how it fails, what happens on a repeat, what it may touch and what shows it worked. Writing one does not require writing code; module 7 applies the same approach to a quote-comparison program for readers on the software path. The access line gets the most attention here, because it is where an intended scope is most often mistaken for an enforced one.

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

The contract, line by line

A is the written specification of one tool: purpose, inputs, output, errors, retry behavior, access and completion evidence. It is the tool's counterpart to module 3's delegation brief, and it answers the same question from the other side: the brief says what the task may do, and the contract says what one operation will do. Here is the contract for find_supplier, authored for the lesson.

Tool: find_supplier

Purpose: return the approved-supplier records whose name contains the given text,
  so that a quote can be matched to the committee's approved list.

Inputs: name (text, required). Matching ignores letter case. Optional: category
  (one of the schema's categories) to narrow the search.

Output: returned_count, skipped_count, complete (true or false), and a list of records
  with id, name, category, contact, approved_on, notes, and source (file path and row
  number), in table order. complete is true only when every row of the table was read
  and checked; a result with skipped_count above zero is marked complete: false, and
  zero returned records with complete: false means the search was not exhaustive,
  not that nothing matches.

Errors (returned instead of output, never as an empty list):
  file-not-found: the table could not be opened; the path is named; no rows were read.
  invalid-input: name missing or empty; category not in the schema's list.
  A row that does not match the schema is not an error: the row is skipped, counted
  in skipped_count with its row number listed, and the output is marked incomplete.

Retry: this tool only reads. A repeat after a lost response changes nothing in the
  table; it returns whatever the table holds at that moment, which may differ from an
  earlier result if the table was edited, or a fresh error. Each attempt uses one file
  read and must be authorized like the first.

Access, intended: reads Documents/Garden/Suppliers/approved-suppliers.csv and nothing
  else that belongs to the task.
Access, effective: the harness runs the tool inside a sandbox that permits reading
  that one file and an explicit allowlist of runtime files, denies every other file
  read, all writes and network access. Enforced by the sandbox,
  within the coverage its documentation states. The credential the process runs under
  can read the whole Suppliers folder; the sandbox, not the credential, narrows it.

Completion evidence: the returned source locations can be opened and compared with
  the returned records; the action record shows the call and its observation.

Each line comes from an earlier lesson. Purpose and inputs are the tool's description, the part MCP discovery carries to the model (lesson 1). Output states the shape lesson 3 asked for: named fields, identifiers, source, and completeness disclosed rather than assumed, so that a zero cannot pose as an exhaustive search when rows were skipped. Errors are separate and named, so that lesson 3's empty-versus-failed confusion cannot occur. Retry states what a repeat does, which for a read is simple, and for a change would name how the server recognizes a repeat. Completion evidence names what a person will check, which is module 3's habit applied to one operation. Access is written twice, and the next section says why.

Two things the contract does not do are worth stating. It does not make the tool behave this way; it is what the tool's builder commits to and what a caller can test against, one call at a time: search for Parkside and count the rows, remove the configured table in a test environment and inspect the error. And it does not tell the model when to call the tool. That is the skill from lesson 2, and keeping the two documents apart is what lets a procedure change without the operation changing.

The access line: intended scope and effective scope

The contract's intended access is a sentence about what the tool is meant to touch. Its effective access is a sentence about what some software will refuse. They are written separately because they often differ, and the gap between them is where trouble lives. In the authored contract the process's credential can read the whole Suppliers folder. Folder permissions alone would therefore not enforce the single-file claim; a tool that read a second file in that folder would succeed. Only the sandbox, configured to permit one file, turns the intended scope into an effective one, and even then only for the routes the sandbox's documentation says it covers. Had the contract listed only the folder permission as its enforcer, the honest effective line would have read: may read any file in the Suppliers folder.

A short dated example shows how an intended scope gets mistaken for an effective one. Earlier revisions of MCP included a feature called roots. The November 2025 specification described it as a way for the client to tell a server which folders the server should work within, and its security section required clients to control access and recommended that servers validate paths and respect the boundaries they were told about. 3 Those are duties assigned to implementations. A server that ignored its roots violated the specification's guidance and whatever access requirements its operators had set, but nothing in the operating system knew the list existed, so no refusal followed. The July 2026 revision deprecated roots, along with two other features; its changelog says new implementations should not add them and suggests passing directories or files as tool inputs, resource addresses or server configuration instead. 2 The lesson survives the feature: a product that says an agent is “scoped to” a folder has described an intention or a setting, and the question is still which software refuses an operation outside it.

An enforced scope has three parts to read, and one product's documentation shows the shape. Claude Code's documentation for its sandboxed shell tool, read on 29 September 2026, describes the operating system enforcing which files and network destinations a shell command and its child processes may reach, so that the limit holds regardless of what the model chose to run. The same page lists what the limit does not cover: it applies to shell commands and not to the product's other tools, which run under the permission rules instead; a command that cannot run inside the sandbox may, unless a setting forbids it, be retried outside it through the ordinary approval prompt; and the network restriction limits destinations without inspecting what is sent to an allowed one. 18 That is a vendor's account of its own product on one date, and it will change. It is here because it names the three things an effective access line has to name: what is covered, what enforces it, and the routes it leaves open. Module 3's sandbox definition already said a boundary has a scope; this is what reading the scope looks like.

A credential's authorization is the other common enforcer, and it has the same three parts. GitHub, a service for storing software projects, documents tokens that can be limited to particular projects and to particular permissions, such as read without write, chosen when the token is created. 19 A connection that presents such a token can ask for what the token allows and nothing more, and GitHub's servers refuse the rest. Notice what that enforces and what it does not: the token limits the requests the service will accept, and says nothing about what the requesting program may do with its own local files, or what the service's own program can reach internally on the service's side. Each enforcer covers its own route.

What each observation can show about scope

The checkpoint asks how to verify that an operation stayed within its allowed scope. The honest answer is that different observations support different claims, and none of them supports the strongest one. Here is what each shows.

A refused request in the action record, a permission-denied error or a forbidden status, shows that one enforcer refused one request on one route. That is evidence that the enforcer exists and covers that route. It is not evidence that no other route exists.

The absence of any refusal shows nothing on its own. It is consistent with an operation that stayed in scope, and with an enforcer that did not cover the route the operation used.

The enforcer’s documented coverage describes which routes it is intended to check. Verify that the relevant configuration was active during the run. A route outside this enforcer’s coverage may have a different control, or none. A successful operation through an active, correctly functioning boundary supports a narrower conclusion: that boundary permitted this operation. It does not establish that every other route was covered.

Comparing file contents before and after the run reveals net changes. Identical contents cannot rule out a write followed by restoration. Reading may update access metadata without changing contents, so timestamps need interpretation too. An unchanged folder cannot establish that other files were not read.

A log of what the process or the service actually did, where one exists, shows reads as well as writes, within its own completeness. Logs can be incomplete, can cover one route and not another, and can be written by the software whose behavior is in question. Read the log's coverage as you read the enforcer's.

What you cannot do is verify scope from the model's report. “I only read the suppliers file” is a generated sentence, and module 1's rule about claims and receipts has not stopped applying. Put together, the strongest available conclusion is usually of this form: the recorded call succeeded under the configured boundary; inspected file contents have no net changes; and other reads or writes are known only as far as the available records cover them.

Transfer checkpoint: a library's reservation lookup

Try the module's distinctions on a case that is not the garden. Everything here is authored.

You help run a small community library. Members reserve books, and reservations are kept by an online service the library subscribes to. A volunteer has set up a fictional harness with an MCP server that the service's vendor supplies, which offers two tools: find_reservation, taking a member's name and matching any member whose name contains it, and cancel_reservation, taking a reservation identifier. The server presents the library's account credential, which the service has authorized to read and to cancel. The harness's rules run reads without asking and ask before cancel_reservation. The vendor's description says the server is “scoped to your library's reservations.” A member named Sam Reid asks by email whether their reservation for a particular book is still active. The library has two members named Sam Reid, and each currently holds one reservation. The organizer asks the harness to find out.

Before reading the guide, write answers to four questions. First, using lesson 3, what should find_reservation return for “Sam Reid,” and what would a poorly designed tool do? Second, write the intended and effective access lines of find_reservation's contract: what it is meant to touch, what software refuses the rest, and what that enforcer does not cover. Third, the vendor's phrase “scoped to your library's reservations” describes what, in this module's terms, and what would you need to see to treat it as an effective scope? Fourth, the model finds the reservation and proposes cancel_reservation because the member's email mentioned they might not need the book; what does this module say about that proposal, and which layer will decide whether it runs?

Self-review guide. A complete answer says find_reservation should return every reservation held by any matching member, here two, each with the reservation identifier, an identifier for the member so that the two Sam Reids can be told apart, and enough source information to check, with the count and a statement that the list is complete; a poorly designed tool would return one Sam Reid's reservation as if it were the only one, and the operation would succeed while the answer misled. For the access lines, it says the intended access is the library's reservations on the vendor's service; the effective access is whatever requests the service accepts from the library's credential, refused by the service's servers, and that this enforcer covers requests to the service and not the server program's local behavior or the vendor's internal access to the data. It notices that the credential also allows cancellation, so the read tool's intended access is narrower than what the credential permits, and nothing named in the description enforces that narrower line. For the vendor's phrase, it says the phrase describes intended scope, like the deprecated roots feature, and that treating it as effective would need the service's documentation of what the credential is authorized for and, ideally, evidence such as a refused request on a covered route. For the proposal, it says the member's email was not a request to cancel and the organizer's request was to find out, so the proposal is outside the task; that the harness's ask rule, module 3's second layer, is what stands between the proposal and a cancellation; and that a cancellation is an external effect that reading the reservation back cannot undo, so the organizer should decline at the prompt and answer the member instead. A strong answer adds that if cancellation should never be possible from this harness, the durable fix is a credential without cancel authorization, enforced by the service, rather than an instruction. Naming the terms without saying why each applies to this record is not yet a complete answer.

Carry the module into the next

The module has compared interfaces by what they do: which route reaches an operation, what its contract promises, and which software enforces the access line. The next module compares whole setups, which means the model, the harness, its connections, where the data goes and what it costs, against a task with constraints. The vocabulary from this module is what lets that comparison be about capabilities rather than brand names: when two products both list an integration, you can now ask which route it uses, what its contract says, and what enforces its scope.

Carry this forward

  • A tool contract states purpose, inputs, output with disclosed completeness, errors, retry behavior, access and completion evidence. It is what a builder commits to and a caller can test one call at a time; it does not say when to use the tool, which is a procedure's job.
  • Write access twice: the intended scope, and the effective scope with its enforcer and that enforcer's coverage. MCP's roots feature, deprecated in July 2026, stated scope without enforcing it; a sandbox or a credential's authorization enforces on the routes it covers, and folder permissions alone do not enforce a single-file claim.
  • Different observations support different claims: a refusal records one rejected operation; documentation describes intended coverage; before-and-after contents reveal net changes; a log shows the actions it recorded. None alone proves that all possible routes stayed within scope.
  • Compare setups by these capabilities: which route an integration uses, what its contract says and what enforces its scope, rather than by the names on the product page.

Lesson check

A vendor's MCP server description says it is “scoped to the Suppliers folder.” The harness's shell tool runs under an operating-system sandbox that, per its documentation, covers shell commands and not MCP servers. Which statement follows from this lesson?

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.

You have reached the end of module 5. The module quiz below checks how these ideas fit together before module 6 compares whole setups against a task.

Module 5 quiz: put the ideas together

1. A product page says its harness “is an MCP host that connects to remote servers.” In this course's vocabulary, what is being described?
2. An organizer connects an MCP server for the committee's supplier service and expects the agent now to know the committee's rule that every quote must be matched to the approved list before use. What does this module say?
3. A find_supplier tool is redesigned to return only the supplier's name and contact, because the identifiers looked like clutter. Later a skill step needs to record which Parkside row was used. What follows from this lesson?
4. A harness sends add_supplier for Millbrook Timber and no response arrives. The service's documentation says nothing about recognizing repeated requests. Which statement follows?
5. The organizer's harness has no execution environment. The supplier table has four hundred rows and the task needs the six fencing suppliers approved this year. Which remedy does this module offer first?
6. A colleague reads an older MCP guide and says a server is safe to connect because the client sends it a roots list naming the allowed folder. What does this lesson say?
7. After a run, the model's final message says “I only read the suppliers file.” The action record shows one find_supplier call with a two-row observation and no errors. What is the strongest conclusion available?

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.

Sources · Reviewed 2026-09-29
  1. 3. Model Context Protocol: Roots (2025-11-25 specification, deprecated in 2026-07-28)
  2. 2. Model Context Protocol: Key changes in the 2026-07-28 revision
  3. 18. Claude Code documentation: Configure the sandboxed Bash tool
  4. 19. GitHub Docs: Managing your personal access tokens

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.