DEV Community: Kiran Manne

Designing tools so an LLM actually calls them correctly: 5 patterns from the CCA-F blueprint

Kiran Manne — Sun, 28 Jun 2026 23:00:00 +0000

> **Update (July 2026):** the certification this maps to now runs on
> Pearson VUE as **CCAR-F** (formerly community-abbreviated CCA-F), with
> multiple-response items added. The Tool Design & MCP domain and its 18%
> weight are unchanged. Details: [CCAR-F vs CCA-F: what actually changed](https://claudecertifiedarchitect.dev/ccar-f-vs-cca-f).

The first time I shipped a tool-using agent, it kept calling the wrong tool. Not occasionally — often enough that I couldn't ship it. The tools worked. The schemas were valid. The descriptions were technically accurate. The model still picked the wrong one, over and over.

What I learned, painfully, is that designing a tool for an LLM caller is closer to writing technical documentation than writing a function signature. The model is reading your tool definition as part of its decision about whether and how to invoke it. If the description is ambiguous, the model is going to guess — and you don't want that.

This post walks through five patterns I now use by default, all of which map directly to material in the Tool Design & MCP domain of the Claude Certified Architect Foundations exam (which is, not coincidentally, the domain where a lot of strong backend engineers lose points).

Pattern 1: Treat the tool description as a prompt, not a docstring

The most common anti-pattern: writing the tool description the way you'd write a Python docstring.

{
  "name": "get_user",
  "description": "Returns the user object for a given user ID.",
  "input_schema": {
    "type": "object",
    "properties": {
      "user_id": { "type": "string" }
    },
    "required": ["user_id"]
  }
}

That description tells the model what the tool does. It does not tell the model when to call it, when not to call it, or what "user object" actually contains. So the model has to guess.

The rewrite:

{
  "name": "get_user",
  "description": "Fetch a user's profile (name, email, plan tier, signup date) by their internal user ID. Use this when the user is asking about a specific account and you have a user ID. Do NOT use this for email-based lookups — use lookup_user_by_email instead. Returns null if the user does not exist; does not raise.",
  "input_schema": { ... }
}

The rewrite answers four questions the model would otherwise guess at: what's in the response, when to use it, when not to use it, and what happens on the unhappy path. That's the bar.

Heuristic: if your tool description doesn't contain the word "when", it's probably not finished.

Pattern 2: Tighten the schema until ambiguity is impossible

LLMs are excellent at producing plausible-looking arguments. They are less excellent at producing correct arguments when the schema admits ambiguity.

A loose schema:

{
  "properties": {
    "status": { "type": "string" },
    "priority": { "type": "string" },
    "date": { "type": "string" }
  }
}

The tightened version:

{
  "properties": {
    "status": {
      "type": "string",
      "enum": ["open", "in_progress", "closed"],
      "description": "Current status of the ticket."
    },
    "priority": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4,
      "description": "1 = urgent, 4 = low. Default to 3 if unspecified."
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "ISO 8601 date (YYYY-MM-DD), in UTC."
    }
  }
}

Three changes, each of which removes a class of failure:

status is now an enum. The model can't invent "pending" or "new".
priority has a documented scale and a documented default. The model isn't guessing whether 1 or 4 is higher priority.
date has a format and a timezone convention. The model isn't deciding whether to write "tomorrow" or "2026-05-30".

Every time you let the model improvise on a string field, you're paying for that improvisation in tail latency and bug reports.

Pattern 3: Make errors teach

This is the single pattern that made the biggest difference to my own agent's reliability, and I think it's badly underrated.

When a tool fails, the model will see the result as part of the next turn's context. If your error is uninformative, the model has nothing to act on. If your error is structured and instructive, the model can recover on its own — no retry logic, no human in the loop.

Bad:

{ "error": "bad input" }

Better:

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No user exists with id 'usr_9k2x'.",
    "hint": "If you only have an email address, call lookup_user_by_email instead."
  }
}

The hint field is the one that earns its keep. It turns the tool's error path into a redirect. The model reads the hint, calls the right tool on the next turn, and the agent loop closes successfully without the user ever seeing the failure.

A good rule: every error your tool returns should answer the question "what should the model do differently next time?"

Pattern 4: One tool, one job

There is a strong temptation, especially if you've written REST APIs, to design a single tool with a mode or action parameter that switches behavior:

{
  "name": "manage_ticket",
  "description": "Create, update, close, or reopen a ticket.",
  "input_schema": {
    "properties": {
      "action": { "enum": ["create", "update", "close", "reopen"] },
      "ticket_id": { "type": "string" },
      "title": { "type": "string" },
      "body": { "type": "string" }
    }
  }
}

This looks elegant. It is, in practice, worse than four separate tools.

Reasons:

The model has to reason about which fields are required for which action. ticket_id is required for update/close/reopen but not create. The schema can't enforce that without oneOf, and even with oneOf, the model's adherence rate drops.
The description has to cover four behaviors, which dilutes the "when to use" signal.
Error messages become generic. "missing required field" is less useful than "close_ticket requires ticket_id".

The rewrite is four tools: create_ticket, update_ticket, close_ticket, reopen_ticket. Each has a focused description, a tight schema, and instructive errors. The model picks correctly more often, and when it doesn't, the failure is local to one tool, not the whole multiplexer.

The exception: if you have genuinely dozens of near-identical operations (CRUD over hundreds of resource types), at some point a parameterized tool wins on context window cost. That tradeoff is real, but it shows up later than people think.

Pattern 5: Design for parallel calls, not just sequential ones

When the model emits multiple tool_use blocks in a single turn, the runtime executes them in parallel and returns all results before the next model call. This is the agent loop's most underrated feature, and it's the one most tool designs accidentally break.

A tool is parallel-safe when:

It is idempotent, or at least non-destructive when called once.
It does not depend on state mutated by another tool call in the same turn.
Its result is interpretable without reference to other concurrent results.

A tool is not parallel-safe when:

It mutates shared state (counters, queues, locks).
It depends on a previous call's output as input.
It returns results that are only meaningful in a specific ordering.

If you have tools that aren't parallel-safe, document that explicitly in the description: "This tool must be called after fetch_session and not in parallel with other write operations." The model will respect that.

The deeper point: when you design a new tool, ask yourself "what happens if the model calls this twice in the same turn?" If the answer is "undefined behavior", you have more work to do.

A short MCP note

If you're exposing tools through the Model Context Protocol (MCP), all five patterns still apply — the protocol just standardizes how the host discovers and invokes them. MCP adds two adjacent primitives worth knowing:

Resources are read-only, addressable content (a file, a database row, a URL). The model can reference them by URI.
Prompts are reusable, parameterized templates the host can offer to the user.

The practical implication: if your tool is fundamentally "give me the content of X", it might want to be a resource, not a tool. Resources are cheaper to expose, easier to cache, and don't burn an agent-loop turn to read.

Closing

Most "the model called the wrong tool" bugs are not model bugs. They're tool design bugs surfaced by the model's willingness to guess when the design is ambiguous. The five patterns above — descriptions that say when, tight schemas, instructive errors, narrow tools, and parallel-safety — close the ambiguity gaps that LLMs are most likely to fall into.

If you're studying for the Claude Certified Architect Foundations exam, the Tool Design & MCP domain (18% of the blueprint) is heavy on scenario questions that test exactly these tradeoffs. The independent practice platform I run at claudecertifiedarchitect.dev has a free 15-question set — a few of them in this domain — if you want to calibrate where you currently stand. It emails you a diagnostic at the end; no payment to try it.

Not affiliated with Anthropic; just a thing I built because I wanted blueprint-weighted practice that didn't exist yet.

A 6-week study plan for the Claude Certified Architect Foundations exam, based on the published blueprint

Kiran Manne — Fri, 26 Jun 2026 22:32:33 +0000

> **Update (July 2026):** the exam moved to Pearson VUE under its official
> code **CCAR-F** — "CCA-F" was always the community abbreviation — and now
> mixes multiple-choice with **multiple-response** items ("select TWO").
> The blueprint this plan is built on is unchanged, so the plan still works
> as written; just add multiple-response drills in weeks 5–6. Full
> before-and-after: [CCAR-F vs CCA-F: what actually changed](https://claudecertifiedarchitect.dev/ccar-f-vs-cca-f).

When I started preparing for the Claude Certified Architect Foundations (CCA-F) exam, the first thing that surprised me was how many people were studying for it the way you'd study for a generic LLM cert: heavy on prompt engineering tricks, light on the actual architecture material.

The published blueprint tells a different story. If you let the weights drive your hours instead of your comfort zone, you end up with a very different study plan than the one most candidates are running.

This is the plan I'd give myself if I were starting over. It's six weeks, roughly 6–8 hours per week, and it's organized around the actual blueprint, not vibes.

The blueprint, before anything else

The CCA-F is a 60-question, 120-minute exam. Scoring is scaled 100–1000, with 720 to pass. The blueprint is split across five domains:

Agentic Architecture — 27%
Claude Code — 20%
Prompt Engineering — 20%
Tool Design & MCP — 18%
Context Management — 15%

The single most useful thing I can tell you is this: Agentic Architecture is the largest domain, and it's the one most engineers under-prepare on. Prompt Engineering feels familiar, so it absorbs disproportionate study time. Agentic Architecture feels abstract, so it gets skipped until the last week. Reverse that instinct.

A quick sanity check on hour allocation across six weeks at ~7 hours/week (42 hours total):

Agentic Architecture: ~11 hours
Claude Code: ~8 hours
Prompt Engineering: ~8 hours
Tool Design & MCP: ~8 hours
Context Management: ~6 hours
Mock exams and review: built into weeks 5–6

Now the week-by-week plan.

Week 1 — Agentic Architecture, part 1

Goal: stop thinking about Claude as a chat completion endpoint.

The core mental model you need is the agent loop: the model emits a response, the runtime inspects stop_reason, dispatches tool calls if needed, appends results back into the conversation, and re-invokes the model. That loop is the unit of work the exam tests, not the single API call.

Things to be solid on by end of week 1:

The four common values of stop_reason (end_turn, tool_use, max_tokens, stop_sequence) and what the orchestrator should do in response to each one.
The difference between a single-turn tool-use request and a multi-turn agentic loop.
Why you append tool_result blocks to the conversation history rather than re-prompting from scratch.
When to terminate the loop (budget, max iterations, end_turn, explicit user interrupt).

A useful exercise: sketch the pseudocode for an agent loop on paper, without looking. If you can't write the while loop and the stop_reason branches from memory, you're not ready to move on.

while True:
    response = client.messages.create(
        model=model,
        messages=history,
        tools=tools,
        max_tokens=4096,
    )
    history.append({"role": "assistant", "content": response.content})

    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "tool_use":
        tool_results = run_tools(response.content)
        history.append({"role": "user", "content": tool_results})
        continue
    if response.stop_reason == "max_tokens":
        # decide: continue, summarize, or fail
        break

That snippet is the spine of half the Agentic Architecture domain.

Week 2 — Agentic Architecture, part 2 + Context Management

Now layer on the failure modes the exam loves to ask about.

Runaway loops. What stops a model from calling the same tool 40 times? You need a story for max iterations, budget guards, and idempotency.
Subagents and orchestrators. When does it make sense to spawn a subagent vs. continue in the same context? What does the orchestrator own that the subagent doesn't?
Parallel vs. sequential tool calls. When the model emits multiple tool_use blocks in one turn, the runtime executes them in parallel and returns all results before the next model call.

Then pivot into Context Management, which is the smallest domain (15%) but heavily intertwined with Agentic Architecture. Focus on:

The structure of the context window (system, conversation history, tool definitions, tool results).
Strategies for long-running agents: summarization checkpoints, scratchpads, external memory, retrieval-augmented context.
The cost of context bloat — both literal dollars and quality degradation.
Caching: what's eligible, what isn't, and the prefix-stability rule that makes it actually work.

Week 3 — Tool Design & MCP

This is the domain where engineers with strong backend backgrounds tend to overestimate themselves.

The trap: you already know how to write a good function signature for a human caller. Writing a good function signature for an LLM caller is a different discipline. The model is reading your description as part of its decision about whether and how to invoke the tool.

Key things to internalize:

Tool descriptions are prompts. They should describe when to use the tool, not just what it does.
Parameter schemas should be tight. Enums beat free-text strings. Required fields should actually be required. Defaults should be documented.
Error returns are part of the interface. A tool that returns "error: bad input" as a string teaches the model nothing. A tool that returns a structured error with a code and a hint lets the model self-correct.
One tool, one job. A do_everything tool with a mode parameter is almost always worse than three narrow tools.
MCP is the protocol layer: how tools, resources, and prompts are exposed to a host. Know the difference between a tool, a resource, and a prompt in MCP terms — that distinction shows up in scenario questions.

If you only do one exercise this week: take a tool you'd normally write for a REST client, and rewrite the schema and description as if the caller were an LLM that has never seen your codebase.

Week 4 — Claude Code + Prompt Engineering

Claude Code is 20% of the exam and it's the most concrete domain. Things to be comfortable with:

The agent loop as it appears inside Claude Code specifically (tool use, file edits, bash, subagents).
CLAUDE.md files and how project-level instructions compose with user-level instructions.
Skills, plans, and how Claude Code structures multi-step work.
Hooks and permissions — what the runtime executes vs. what the model proposes.
Headless mode and the difference between interactive and scripted use.

Prompt Engineering, also 20%, is the domain where most candidates over-prepare. You don't need clever jailbreaks or 50 prompt patterns. You need:

System prompts vs. user prompts and what belongs in each.
Structured output: when to ask for JSON, when to use tool use as a forcing function instead.
Few-shot examples and when they hurt more than they help.
Chain-of-thought and extended thinking — what the difference actually is and when each is appropriate.
XML-style tag conventions Anthropic recommends for delimiting input sections.

The exam is not asking you to write clever prompts. It's asking you to choose the right prompting strategy for a given scenario.

Week 5 — First full mock + targeted remediation

Take a full 60-question, 120-minute timed simulation under exam conditions. No notes, no Claude open in another tab. Then score it by domain.

The pattern you're looking for is not your overall score. It's your lowest-scoring domain weighted by blueprint percentage. A 60% in Agentic Architecture costs you more points than a 60% in Context Management.

Spend the rest of the week drilling whichever domain has the worst weighted gap. Don't review what you already know.

Week 6 — Second mock + light review

Take a second full mock early in the week. Compare to week 5. If your weighted-worst domain hasn't moved, that's where the remaining hours go.

The last two days should be light. Re-read your own notes, not new material. Sleep more than you study.

A few things I wish I'd known earlier

The exam rewards orchestration thinking, not API recall. You will rarely be asked to recite a parameter name. You will frequently be asked to choose between two valid-looking architectures.
Read the scenario stem twice before reading the options. The options are designed to be plausible. The stem usually contains the constraint that makes only one of them correct.
"All of the above" and "none of the above" rarely appear. When two options seem equally right, you've missed a constraint in the stem.
Time pressure is real. 60 questions in 120 minutes is two minutes per question, including re-reads. Practice with a clock.

If you want to drill against blueprint-weighted scenarios while you work through this plan, the practice platform I maintain at claudecertifiedarchitect.dev has a free 15-question set across the five domains (it emails you a diagnostic at the end). It's independent and not affiliated with Anthropic, but the question distribution mirrors the official blueprint, which is the thing that matters most for calibration. The full bank is 1,000+ questions, $24.99 one-time.

Good luck. Study the weights, not your comfort zone.