CCA-F Domain 2 Study Guide: Tool Design & MCP Integration

Core concept. When a tool fails, you return a tool_result with is_error: true. That flag tells Claude the call failed — but the content of that result is what determines whether the agent can recover. A generic string like "Error: request failed" gives the model nothing to reason over. A structured, type-specific error tells it what went wrong, whether the condition is recoverable, and what to try next.

Why it matters. Claude treats a tool_result as data to reason over, not as a fatal exception. A well-formed error result lets the model self-correct — retry after a delay, fix a malformed argument, or fall back to a different tool — without a human in the loop. A vague error usually produces one of two bad outcomes: the model gives up, or it blindly retries the identical failing call. On the exam, the answer that turns a failure into an actionable next step is almost always correct.

Concrete example. A customer-support agent calls an order_lookup tool that hits a rate limit. Instead of returning "failed", return a payload the model can act on:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A7b3",
  "is_error": true,
  "content": "{\"error_type\": \"rate_limited\", \"recoverable\": true, \"retry_after_seconds\": 30, \"suggested_action\": \"Wait 30s and retry the same call, or reduce the page size.\"}"
}

Contrast that with a non-recoverable error — an invalid order ID — where the right suggested_action is to ask the user for a corrected ID rather than retry. Encoding recoverable: false stops the model from looping on a call that can never succeed.

• error_type — a machine-readable category (rate_limited, not_found, invalid_argument, auth_expired) the model can branch on.
• recoverable — a boolean that tells the model whether retrying could ever help.
• suggested_action — the concrete next step, so the model doesn't have to guess.
• Keep is_error: true on the block itself — don't hide the failure inside a success payload, or the model may treat garbage as valid data.

Core concept. Claude picks tools almost entirely from their name and description. The description is prompt real estate, not documentation — it should be *prescriptive about when to call the tool*, specify the exact input format, give a use-case example, and disambiguate the tool from any semantically similar sibling.

Why it matters. Recent Claude models reach for tools more conservatively and follow instructions more literally than older ones. A thin description like "Search records" produces missed calls and wrong-tool selection. Adding an explicit trigger condition ("Call this when the user asks about current prices or recent events") gives a measurable lift in should-call accuracy. When two tools sound alike — search_orders vs search_products — the model needs an explicit boundary or it will confuse them.

Concrete example. A data-extraction agent has two lookup tools. Weak descriptions cause cross-firing; strong ones separate them cleanly:

{
  "name": "lookup_customer",
  "description": "Fetch a customer profile by their exact account ID. Call this when you have an account ID (format: 'ACC-' followed by 8 digits, e.g. 'ACC-10482233') and need contact or plan details. Do NOT use this to search by name or email — use search_customers for that. Example: to answer 'what plan is ACC-10482233 on', call lookup_customer with account_id='ACC-10482233'.",
  "input_schema": {
    "type": "object",
    "properties": {
      "account_id": {
        "type": "string",
        "description": "Exact account ID, format ACC-XXXXXXXX (8 digits)."
      }
    },
    "required": ["account_id"]
  }
}

• Use-case example — show one concrete input the model should produce, inline in the description.
• Input format specification — state the exact shape (ACC- + 8 digits) in both the description and each property's description.
• Disambiguation — name the sibling tool and the boundary between them ("use search_customers for name/email").
• Use enum for fixed value sets and mark only truly required fields as required — a tight schema is itself a selection signal.

Core concept. Integrating an MCP server has three moving parts: (1) pick the right scope so the server loads where you need it, (2) configure authentication without hard-coding secrets — using environment-variable expansion — and (3) verify tool discovery so you know Claude actually sees the tools before you rely on them.

Why it matters. A server that's configured but never connects is invisible to the model; a server with a leaked token in a committed config is a security incident. The integration workflow exists to avoid both. In Claude Code you add a server with claude mcp add, choosing a transport (http, sse, or a local stdio process) and a scope.

# Add a shared, project-scoped server (writes .mcp.json)
claude mcp add --transport http support-db --scope project https://mcp.example.com/mcp

# List servers and their status; then use /mcp inside a session
claude mcp list
claude mcp get support-db

Authentication via environment-variable expansion. In .mcp.json, Claude Code expands ${VAR} (the value of VAR) and ${VAR:-default} (value if set, otherwise default). Expansion works in command, args, env, url, and headers — so the secret stays in the environment, and only its name is committed to version control.

{
  "mcpServers": {
    "support-db": {
      "type": "http",
      "url": "${SUPPORT_API_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${SUPPORT_API_KEY}"
      }
    }
  }
}

Verify tool discovery. Run /mcp inside a session — the panel shows each connected server with its tool count and flags servers that advertise a tools capability but expose none. claude mcp list and claude mcp get <name> report connection status from the command line, and are where you authenticate OAuth servers and see any missing-variable warnings.

Core concept. The tool_choice parameter controls whether and which tool Claude calls. When you need structured output — a classification, an extracted record — forcing a specific tool guarantees the model returns arguments matching that tool's schema instead of free-form prose.

Why it matters. For a data-extraction agent that must always emit a record object, tool_choice: {"type": "tool", "name": "record"} makes the call non-optional — you get schema-valid arguments every time. Any tool_choice can also set disable_parallel_tool_use: true to cap the response at one tool call.

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[extract_ticket_tool],
    tool_choice={"type": "tool", "name": "extract_ticket"},
    messages=[{"role": "user", "content": ticket_text}],
)

Sequencing multi-tool workflows. A dependent workflow must obtain prerequisite data before the tool that consumes it. To answer "what are this customer's recent orders," the agent needs the account ID (from lookup_customer) before it can call list_orders(account_id=...). Parallel tool use is only safe for independent calls — a data dependency is inherently sequential. The usual pattern is to let auto chain the calls turn by turn, feeding each tool_result back before the next step, rather than forcing everything at once.

Core concept. Claude Code configures MCP servers at three scopes, and the choice controls which projects the server loads in and whether the config is shared with your team. The guiding rule: project scope for shared team tooling, user scope for personal or experimental configurations.

Why it matters. Put a server your whole team needs — the shared issue tracker, the project database — at project scope so it's committed in .mcp.json and everyone gets the same tooling on checkout. Keep a personal utility, an experimental server, or anything with credentials you don't want in version control at user scope (available across all your projects) or local scope (default; just this project, private to you). This same project-vs-user reasoning applies to settings generally: shared configuration belongs in version-controlled project files; personal preferences belong in your user configuration.

Concrete example. A team standardizes on a shared support-data server, while one engineer trials a new analytics server privately:

# Shared with the team, committed to .mcp.json
claude mcp add --transport http support-db --scope project https://mcp.example.com/mcp

# Personal, available across all of your projects, not committed
claude mcp add --transport http analytics-beta --scope user https://beta.example.com/mcp

When the same server name is defined at multiple scopes, Claude Code connects once, using the highest-precedence source: local → project → user (then plugin-provided servers, then connectors). The whole entry from the winning scope is used; fields are not merged across scopes.