Claude Architect WorkshopPDFEPUBlearnwithparam.comkaas.team

Professional, lesson 11

MCP, API or agent-to-agent

Choose MCP, a direct API or agent-to-agent by who reuses it

Every request to the Lumen support agent carries 140 tool definitions, because each team added its own. Nobody chose a mechanism. The cost per call is high, and two teams wrote the same lookup twice. This is the support agent at Lumen Supply, an online electronics shop. You will send all 140 tools, read what it costs, then fix two functions so each need gets one mechanism and each request carries a handful of tools.

I doWatch the failure and its fix.

140 tools in every request

The registry holds 140 tools, 7 actions for each of 20 areas. Thirty labelled requests fall into three kinds of need.

A shared lookup is used by three teams. A one-off is used by one. Another team's agent already owns a decision.

Three things go wrong, in this order. All 140 tools go out on every call. Each team wires its own integration. And no rule says when to use MCP, a direct call or another agent.

Choose how a need is served, then send only the tools it needs.Needwho reuses itchooseMCP, direct or agentdiscoverthe few tools that fitClaudecalls one toolboth rules are written in mechanism.pyChoose how a need is served, then send only the tools it needs.Needwho reuses itchooseMCP, direct or agentdiscoverthe few tools that fitClaudecalls one toolboth rules are written in mechanism.py

Discover the few tools a request needs

A caller asks for the order record O-1002. The code sees that three teams use the lookup, so it picks a shared MCP server. It then searches the registry and sends 8 definitions, not 140.

Open the cards to read the definitions that were sent and the call the model made. The request cost about 1,200 input tokens.

  1. RequestGet the order record O-1002.
    Show the result
    Get the order record O-1002.
  2. Registrysends 8 tool definitions, 1,180 input tokens
    Show the result
    8 tool definitions of 140
1,180 input tokens
  3. Mechanismserves it with a shared MCP server
    Show the result
    mcp
  4. Claudecalls orders_get
    Show the result
    orders_get

The need got its mechanism and the right tool was called.

The choice rule, written as code

Two functions hold the design. The file shown is the starting one. The choose function should return MCP for a shared need. It should return a direct call for a one-off, and an agent call when another team owns the decision.

discover should return the few tools that fit the request. The more definitions a request carries, the more the model has to tell look-alike tools apart, and the more it costs.

starter/mechanism.py
1"""EDIT THIS FILE. The integration has two planted defects.21. choose(): every team wires its own call, whatever the need.32. discover(): every request carries all 140 tool definitions.45Run `./workshop check integration-mechanism` until it is green, then6`./workshop watch integration-mechanism`.7"""89from app.data import REGISTRY10from kit.api import Json111213def choose(need: Json) -> str:14 """The mechanism for a need: "mcp", "direct" or "agent"."""15 return "direct"161718def discover(query: str) -> list[Json]:19 """The tool definitions a request carries."""20 return REGISTRY

Should every tool go in every request?

A teammate says the model should see all 140 tools on every call, so that it never lacks the one it needs.

Predict: Should every tool go in every request?

  1. AYes, the model needs to see all of them.
  2. BNo, send the few it needs, found by query.
Show the answer

B. More definitions cost tokens and blur the choice. Discover the few that fit, and send those.

All 140 tools on every call

This is a real Claude Haiku 5.5 run, recorded once and replayed here. The request carried 140 definitions and about 10,700 input tokens. The starting choose returns a direct call for every need.

The model picked the right tool this time, so the harm here is cost and the wrong mechanism.

The run is marked wrong for two reasons. A lookup that three teams use went out as a direct call. And 140 definitions is more than the 10 the rule allows.

  1. RequestGet the order record O-1002.
    Show the result
    Get the order record O-1002.
  2. Registrysends 140 tool definitions, 13,153 input tokens
    Show the result
    140 tool definitions of 140
13,153 input tokens
  3. Mechanismserves it with a direct call
    Show the result
    direct
  4. Claudecalls orders_get
    Show the result
    orders_get

The mechanism, the tool or the tool count was wrong.

Look-alike tools get mixed up

A clear request is not the test. The same 140 tools also hold a get tool and a search tool for each area, and they read alike. So eight lookups, each worded as "Show me the invoice for order O-1007", went out with all 140 tools.

In these eight runs, 8 of 8 called a look-alike tool. Six called a search tool where a get by id was meant, and two called the order tool for a refund or a warranty.

Each request was 10,667 or 10,668 input tokens. The wording leaves the choice open, and a big list of near twins is where it goes wrong.

This part is interactive in the lab: run ./workshop watch integration-mechanism.

Choose by reuse, discover by query

choose maps a need to a mechanism. Another team's agent wins first. Then a need used by two or more teams gets MCP. The rest get a direct call. discover scores every tool against the request and returns the top 8.

The arithmetic is plain. A request that carries 140 definitions bills about 10,700 input tokens. Across 10,000 calls a day that is about 107 million tokens. Eight definitions bill about 1,200 tokens, or about 12 million.

The request, the tools sent and the tool called.RequestRegistryClauderequest8 tool definitionsorders_get
mechanism.pygreen lines are what the fix adds
1"""Choose a mechanism by reuse, and discover tools by query."""23from app.data import REGISTRY4from app.discovery import scores5from kit.api import Json67TOP = 88SHARED = 291011def choose(need: Json) -> str:12 """Another team's agent, a shared server, or a direct call."""13 if need["agent"]:14 return "agent"1516 return "mcp" if need["teams"] >= SHARED else "direct"171819def discover(query: str) -> list[Json]:20 """The few tool definitions that fit a request, best first."""21 ranked = sorted(22 zip(scores(query, REGISTRY), REGISTRY, strict=True),23 key=lambda pair: -pair[0],24 )2526 return [tool for _, tool in ranked[:TOP]]
We doChange one setting at a time and predict.

The same input now ends well

Use the switch to run the same request with all 140 tools and then with the discovered 8. The card marked "This is where the runs split" shows the tool count.

The all-tools run sent 140 definitions and used the wrong mechanism. The discovered run sent 8, used MCP, and called the same tool.

This part is interactive in the lab: run ./workshop watch integration-mechanism.

Try it: delivery and need

Change one setting at a time. Pick a need, then switch between all tools and discovered tools. Every combination is a recorded run, so this works with no internet.

For the one-off, a direct tool is right, and the discovered run only trims the list. For the other team's agent, the answer is a call to that agent, and the code never rebuilds its rules. A small set of stable tools can also sit in a cached prefix, which keeps it cheap with no discovery step.

This part is interactive in the lab: run ./workshop watch integration-mechanism.

When MCP earns its place

A shared server serves many agents from one place. One owner keeps the tool current, and a fix reaches every agent. A one-off does not need that, and a server for it costs more than it returns.

A server also holds the role's tool list. A tool outside that list cannot be called, whatever the prompt says. Enforce in managed settings and hooks shares settings across teams.

starter/mechanism.py
1"""EDIT THIS FILE. The integration has two planted defects.21. choose(): every team wires its own call, whatever the need.32. discover(): every request carries all 140 tool definitions.45Run `./workshop check integration-mechanism` until it is green, then6`./workshop watch integration-mechanism`.7"""89from app.data import REGISTRY10from kit.api import Json111213def choose(need: Json) -> str:14 """The mechanism for a need: "mcp", "direct" or "agent"."""15 return "direct"161718def discover(query: str) -> list[Json]:19 """The tool definitions a request carries."""20 return REGISTRY
You doFix the starting code, then test yourself.

You do: pick the mechanism and discover the tools

Copy the starting code and open work/integration-mechanism/mechanism.py. choose() wires a direct call for every need, and discover() sends all 140 tool definitions with each request.

Terminal
./workshop start integration-mechanism
./workshop check integration-mechanism
./workshop watch integration-mechanism

The checks want a shared server for a shared need, a direct call for a one-off and a call to another team's agent rather than a rebuild. A request carries few definitions, and discovery finds the right tool near the top.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

1. Three teams at a shop each wrote their own order lookup for the support agent, and the 3 copies returned different fields last week. Each copy has its own owner and its own deploy. The lookup will be reused by a fourth team next month. Which integration fits a need that several teams reuse?

  1. ALet each team keep its copy and add a test that compares the outputs.
  2. BWrap the lookup in a prompt that every team pastes into its agent.
  3. CRun one shared MCP server for the lookup, with one owner.
  4. DPut the lookup in a shared document that agents read.
Show the answer

Answer: C

  • A A test that compares 3 copies finds drift after it happens. The lookup still exists 3 times and needs 3 fixes.
  • B A prompt describes a tool, and it does not run one. Each team would still need its own code behind it.
  • C Correct. A shared server serves every agent from one place, so a fix by its one owner reaches all 4 teams.
  • D A document cannot query an order. The agent needs a tool that returns the live record.

2. An engineer needs one unit conversion, from kilograms to pounds, inside a single script that runs once a week. No other team has asked for it, and a shared MCP server would take about a week to build and host. The script already calls the Messages API. What is the sound mechanism?

  1. AStand up an MCP server, since every tool should be served that way.
  2. BHand the conversion to another team's agent and wait for its reply.
  3. CAvoid direct tools, since a direct call is the legacy way.
  4. DWrite the conversion as a direct tool in the script's own request.
Show the answer

Answer: D

  • A A server pays off when several agents reuse the tool. One script that runs once a week gains nothing from it.
  • B A call to another agent adds a round trip and a dependency for a sum the script can do itself.
  • C A direct tool is not legacy. It is the plain choice when one caller needs it and nobody else does.
  • D Correct. With no reuse, a direct tool in the request is the smallest thing that works.

3. The refunds team already runs an agent that decides whether an order qualifies for a refund, with its own rules and its own tools. The support team needs the same decision for 30 tickets a day and must not copy the rules. The refunds team changes its rules every month. What should the support agent do?

  1. ACopy the refunds rules into the support prompt and update them monthly.
  2. BCall the refunds team's agent with the question and use its answer.
  3. CExpose each refunds tool to the support agent as its own tool.
  4. DAsk the refunds team for a list of rules each month.
Show the answer

Answer: B

  • A A copy drifts the month the refunds team changes a rule, and nobody is told.
  • B Correct. The other team's agent owns the decision, so a call to it keeps the rules in one place.
  • C That rebuilds the refunds logic in the support agent, with the rules spread across two teams.
  • D A monthly list is a copy that goes stale between one month and the next.

4. A design review compares a shared MCP server with one direct tool per agent for a lookup that 5 agents will use. The server costs a week to build, and each direct copy costs a day. Select two reasons that favour the shared server.

  1. ASeveral agents reuse the tool from one place.
  2. BMCP is the newer way, so it is the better default.
  3. COne owner keeps the tool current for every agent.
  4. DA server makes the model call the tool more often.
Show the answer

Answer: A, C

  • A Correct. Reuse is the test, and 5 agents reusing one lookup pay back the week.
  • B Age is not a reason. A one-off tool gains nothing from a server, however new the protocol is.
  • C Correct. A fix made once by the owner reaches every agent, which 5 separate copies cannot do.
  • D The mechanism does not change how often the model picks a tool. The description does.

5. Every request to a support agent carries 140 tool definitions, about 10,700 input tokens, because each team added its own. Cost per call is high and the agent sometimes picks a look-alike tool. The team needs a change that lowers both. What fits?

  1. AMerge the 140 tools into 20 tools with longer descriptions.
  2. BAsk the model in the prompt to ignore tools that do not apply.
  3. CDiscover a handful of tools by query and send only those.
  4. DMove the whole list to a larger model with a bigger window.
Show the answer

Answer: C

  • A Longer descriptions add tokens, and merged tools hide what each one does. The request is no lighter.
  • B The 140 definitions are still sent and still billed. A line asking the model to ignore them is a request.
  • C Correct. A request that carries 8 definitions costs about 1,200 tokens, and there are fewer look-alikes to confuse.
  • D A larger model reads the same 140 definitions at a higher price. The count is the cost.

6. A support agent uses the same 12 tools on every request, and the set has not changed in 6 months. A proposal adds a discovery step that searches a registry before each call, which adds one round trip of about 300 ms. The prefix is large and stable. What is the better choice?

  1. AKeep the 12 tools in a cached prefix and skip the discovery step.
  2. BAdd discovery anyway, since a smaller request is lighter.
  3. CSplit the 12 tools across 3 agents at random.
  4. DDrop 6 tools to keep the set short.
Show the answer

Answer: A

  • A Correct. A small stable set is cheap when cached, and discovery would add a round trip for no saving.
  • B Discovery pays when the set is large or changing. For 12 stable tools it adds latency and a failure point.
  • C A random split breaks the set so some requests miss the tool they need.
  • D The agent uses all 12, so dropping 6 removes tools it needs.

7. Tool choice accuracy fell from 96 percent to 81 percent after 30 tools were added with overlapping descriptions. Four tools all say they get an order. The team must restore accuracy this sprint without retraining anything. What should it do?

  1. AAdd a prompt rule that says to pick the most specific tool.
  2. BRaise the temperature so the model explores the list.
  3. CAdd 30 more tools so each case has its own.
  4. DTrim the overlap and discover a few tools per request.
Show the answer

Answer: D

  • A A rule cannot separate tools whose descriptions say the same thing. The model still sees four twins.
  • B A higher temperature makes choices less steady, not more accurate.
  • C More tools add more look-alikes, and the choice gets harder.
  • D Correct. Fewer and clearer tools in each request remove the confusion at its source.

8. A cost review looks at an agent that sends all 140 tool definitions on each of 10,000 requests a day. The review asks what sending every tool costs. Select two costs of doing so.

  1. AMore input tokens on every call.
  2. BA lower chance of a cache hit on the answer text.
  3. CMore look-alike tools for the model to confuse.
  4. DA longer output, since the model lists each tool.
Show the answer

Answer: A, C

  • A Correct. 140 definitions come to about 10,700 tokens, and they are billed on each of the 10,000 calls.
  • B The answer text is not cached by its tools. The cost of the tools shows up in input tokens.
  • C Correct. Near-identical descriptions make a wrong pick more likely as the list grows.
  • D The model writes one tool call, not a list of the tools it skipped.

9. A nightly job runs 3 steps in a fixed order for each order, which are fetch the record, check the stock and write a label. The steps never change and each takes under a second. A teammate proposes an agent that decides the order of the 3 tools. What is the better design?

  1. AAn agent, since it adapts to new cases.
  2. BA workflow that calls the 3 tools in code, in order.
  3. CA coordinator agent with 3 sub-agents, one per step.
  4. DAn agent with all 3 tools and a prompt that lists the order.
Show the answer

Answer: B

  • A The steps are known, so the agent adds cost and variance and leaves the order to the model.
  • B Correct. When the path is fixed, code is the workflow, and it runs the same way on every order.
  • C A coordinator and 3 sub-agents add calls and latency to 3 fixed steps.
  • D A prompt that lists the order is a request, and the model can skip or reorder a step.

10. A support agent gets 2,000 different requests a week, and the tool that serves each one depends on the words in it. The steps cannot be fixed in advance, and the registry holds 140 tools. The team wants the model to choose at run time, inside a sensible bound. What fits?

  1. AHard-code 2,000 branches in the workflow, one per request.
  2. BSend all 140 tools and let the model search them.
  3. CLet the model pick from a small set discovered for each request.
  4. DRoute every request to a human, who picks the tool.
Show the answer

Answer: C

  • A Two thousand branches cannot cover next week's requests, and each one needs an owner.
  • B A full list costs about 10,700 tokens on each call and crowds the choice with look-alikes.
  • C Correct. The path depends on the input, so the model chooses, and discovery bounds the list it chooses from.
  • D A human on every request removes the point of the agent and cannot keep up with 2,000 a week.

11. One shared MCP server serves the support role and the billing role. Support may read and update records, while billing may read and refund. A delete tool exists on the server, and the team wants the support role to be unable to call delete or refund. Where is that set?

  1. AIn the role's tool list at the server, so the other tools are not offered.
  2. BIn a prompt line that tells the support agent to avoid delete.
  3. CIn a log alert that fires when support calls refund.
  4. DIn the client, by hiding delete from the support dashboard.
Show the answer

Answer: A

  • A Correct. A tool outside the role's list at the server cannot be called, whatever the client or the prompt says.
  • B A prompt line is a request. A model can be argued out of it.
  • C An alert fires after the refund has been paid, so it reports the harm and does not stop it.
  • D A dashboard is a view for people. The agent's list at the server is unchanged.

12. A discovery step returns 8 tools for a request, and one of them, refunds_update, is not on the caller's role list. The model asks for it, and logs show this happened 3 times this week. The team wants the call to fail with no change to how discovery ranks. Where should it be refused?

  1. AIn the prompt, with a line that lists the tools the caller may use.
  2. BIn the discovery ranking, by scoring the tool lower.
  3. CIn a weekly review of the 3 calls.
  4. DAt the server, which checks the caller's list on each call.
Show the answer

Answer: D

  • A The model can still ask for a tool that is not on the list, and a sentence cannot refuse the call.
  • B A lower score changes the order of the list and does not remove the tool. It can still be returned.
  • C A review after the call finds the change after it was made.
  • D Correct. The server holds the role's list and refuses any call outside it, in code the model cannot skip.

Play: predict the output

This discovery step ranks tools by the words they share with the request.

python
def discover(query: str, top: int = 8) -> list[Json]:
    q = set(query.lower().split())
    ranked = sorted(
        REGISTRY,
        key=lambda t: -len(q & set(t["description"].lower().split())),
    )
    return ranked[:top]

Predict: The request is "where is my parcel", and track_shipment says "Show the delivery status of a shipment." Is it in the top 8?

  1. ANot reliably. It shares no words with the request, so it scores zero.
  2. BYes. Parcel and shipment mean the same thing.
Show the answer

A. Word overlap misses a paraphrase. The lab blends overlap with vector similarity for this reason, and you should test discovery on requests in your customers' own words.

References

Conclusions

  • Choose the mechanism by who reuses the tool: MCP for shared, a direct call for one caller, an agent call for another team's decision.
  • Send the few tools a request needs, found by query, and not the whole registry.
  • Refuse a tool outside the role's list at the server, in code, and not in the prompt.

You can now give each need one mechanism and keep each request small.

MCP server

One shared place that serves a tool to many agents

Direct tool

A tool defined in one caller's own request

Agent call

A request to another team's agent, which owns the decision

Tool discovery

Finding the few tools that fit a request by query

Role list

The tools a role may call, enforced at the server