20 Questions — Domain 2 : Tool Design & MCP Integration

Expand any question to reveal the correct answer and explanation.

1. 1 A solution architect is designing a system where Claude must interact with a legacy database. The architect decides to expose the database schema as an MCP Resource rather than a tool that executes 'DESCRIBE' queries. What is the primary architectural advantage of this decision?

   Consider the difference between taking an action and viewing a catalog of available information.

   It allows Claude to discover the data hierarchy holistically at connection time without wasting reasoning turns on exploratory calls.

   MCP Resources are designed to expose content catalogs and hierarchies, giving the model visibility into available data structures without the overhead of tool execution cycles.

   • ✗ It ensures that the database schema is read-only, providing a system-level security guarantee that a tool cannot offer.

     While Resources are generally read-only, MCP annotations and primitive types are self-reported and do not replace low-level process or network security boundaries.

   • ✗ It bypasses the context window limits by storing the schema in the MCP server's local memory instead of the conversation history.

     Resources must still be read and loaded into the context window for the model to use them; they do not reside externally once the model interacts with them.

   • ✗ It enables the model to perform complex JOIN operations across multiple tables within the Resource definition itself.

     Resources represent static or dynamic data snapshots; complex logic like multi-table joins is typically handled by executable Tools.

2. 2 During a production deployment, an agent with access to 55 tools across four MCP servers frequently fails to select the correct tool, even when provided with explicit instructions. What is the most effective architectural remediation according to Anthropic's 'least-privilege' guidelines?

   Think about the cognitive load on the model when choosing between a large number of options.

   Implement dynamic scoping by exposing only a subset of role-relevant tools to the agent at any given time.

   Decision reliability degrades significantly as the number of available tools increases; limiting access to 4-5 specialized tools improves selection accuracy.

   • ✗ Combine the 55 tools into a single monolithic 'super-tool' with a complex branching logic based on the input parameters.

     Monolithic tools restrict the model's ability to inspect specific parameter requirements and increase the likelihood of input validation failures.

   • ✗ Increase the length of the tool descriptions to at least 500 words to ensure the model has maximum context for selection.

     While clear descriptions are vital, overly verbose descriptions can introduce noise and distract from the core functional boundaries of the tool.

   • ✗ Use 'tool_choice': 'any' to force the model to attempt a tool call on every single turn until it finds the correct one.

     The 'any' configuration guarantees a tool call is made but does not improve the logic or accuracy of which specific tool is selected from a large set.

3. 3 An MCP tool designed for financial transactions returns an error because the requested refund amount exceeds the user's daily limit. Which structured error response configuration best enables the agent to recover or inform the user appropriately?

   How can you distinguish between a network glitch and a strict policy violation?

   Set 'isError': true, 'errorCategory': 'business', and 'isRetryable': false.

   Categorizing the failure as a 'business' rule violation with no retry prevents the agent from wasting tokens on redundant attempts while providing context for a user explanation.

   • ✗ Set 'isError': true, 'errorCategory': 'transient', and 'isRetryable': true.

     Policy violations are not transient network issues; marking them as such would cause the model to retry an action that will never succeed under current rules.

   • ✗ Return a standard HTTP 400 Bad Request status code directly in the tool result string.

     Models reason more effectively over structured metadata fields like 'errorCategory' than raw, unparsed HTTP status codes in text strings.

   • ✗ Set 'isError': false and return the text 'Limit Exceeded' to allow the model to reason about the failure as a successful query.

     Silently suppressing errors prevents the agent from recognizing a failure state, which is an anti-pattern that leads to inaccurate summaries.

4. 4 A developer is configuring an MCP server in a project-level '.mcp.json' file and needs to include an API key for authentication. What is the recommended way to handle this sensitive credential?

   Think about how standard dev-ops practices manage secrets in configuration files.

   Use environment variable expansion syntax like '${API_KEY}' in the '.mcp.json' file.

   Expansion allows credentials to be managed securely in the environment without committing secret keys to version-controlled configuration files.

   • ✗ Hardcode the API key in the 'user-level' configuration file at '~/.claude.json' since that file is never shared.

     While more secure than project-level hardcoding, it lacks portability and prevents team-wide automation using standard CI/CD environment variables.

   • ✗ Pass the API key through a 'system prompt' instruction that the agent uses to populate the tool's 'auth_header' parameter.

     Relying on the model to handle raw credentials increases the risk of prompt injection and accidental disclosure of the key in conversational output.

   • ✗ Encrypt the API key using a Base64 string directly within the 'args' field of the server configuration.

     Base64 is an encoding format, not a security or encryption mechanism, and it still exposes the credential in the source code.

5. 5 In a multi-agent system, the coordinator agent needs to ensure that a specialized 'data_extraction' agent always calls the 'validate_schema' tool before attempting to write to a database. Which 'tool_choice' configuration should be used on the first turn?

   How do you take the choice away from the model to guarantee a specific starting action?

   A forced tool selection object: { "type": "tool", "name": "validate_schema" }.

   Forced tool selection ensures the model executes a specific required step first, allowing the results to inform subsequent reasoning turns.

   • ✗ Setting 'tool_choice': 'any'.

     The 'any' setting guarantees *a* tool is called, but it does not guarantee *which* tool is selected from the available set.

   • ✗ Setting 'tool_choice': 'auto'.

     'Auto' allows the model to decide whether to call a tool or return conversational text, which is unsuitable for enforcing a mandatory sequence.

   • ✗ A list of allowed tools containing only 'validate_schema' with 'tool_choice' set to 'none'.

     Setting 'tool_choice' to 'none' prevents the model from calling any tools, regardless of what is in the allowed list.

6. 6 A solution architect notices that Claude frequently ignores a tool named 'fetch_user_data' in favor of the built-in 'Grep' tool when searching for user profiles. What is the most likely cause and its remediation?

   If the model doesn't know why your tool is better than a standard one, it won't use it.

   The MCP tool description is too minimal; it must be enhanced to explain its specific advantages and specific data access over generic search tools.

   Models use descriptions as the primary heuristic for routing; if a custom tool's purpose is vague, the model will default to familiar built-in capabilities.

   • ✗ The 'Grep' tool has a higher priority ranking in the Claude Agent SDK by default.

     Claude does not use a hidden priority ranking; tool selection is driven by the relevance of descriptions to the current context and goal.

   • ✗ The MCP server is using 'stdio' transport, which has higher latency than the 'API' transport used by built-in tools.

     Transport protocol choice affects execution speed but does not influence the model's high-level reasoning regarding tool selection.

   • ✗ The 'fetch_user_data' tool name contains underscores, which the model interprets as a lower-confidence signal.

     Standard naming conventions like snake_case or camelCase do not negatively impact the model's confidence or selection logic.

7. 7 When building an MCP server that supports both 'stdio' and 'SSE' (Server-Sent Events) transport layers, which factor should most influence the selection of SSE for an enterprise AI application?

   Think about where the server is running relative to the application.

   The requirement for a remote, network-based connection between the Claude client and the MCP server.

   SSE/HTTP allows for client-server communication over a network, whereas stdio is restricted to local process communication (pipe).

   • ✗ The need to bypass the 24-hour latency window associated with synchronous API calls.

     Transport layers are unrelated to the Batch API's processing window; both stdio and SSE handle real-time interactions.

   • ✗ A requirement to reduce the token cost of tool parameter descriptions by 50%.

     The transport protocol does not alter the underlying JSON-RPC payloads or the tokenization of the tool definitions.

   • ✗ The goal of ensuring that tool results are automatically appended to the conversation history.

     Appending results to history is a function of the Agent SDK's agentic loop, regardless of the transport layer used by the MCP server.

8. 8 You are implementing a 'PostToolUse' hook in the Claude Agent SDK to handle data from a legacy MCP tool that returns dates in three different formats (Unix, ISO 8601, and MM/DD/YYYY). What is the critical skill being applied here?

   Why would you want to change the tool's output before the LLM sees it?

   Normalizing heterogeneous data formats into a consistent standard before the model processes the result.

   SDK hooks allow for deterministic data transformation, ensuring the model receives clean, predictable inputs that don't waste reasoning on parsing variations.

   • ✗ Providing probabilistic compliance to ensure the model guesses the correct date format 90% of the time.

     Hooks provide deterministic guarantees; relying on the model to interpret formats is a probabilistic approach that is less reliable.

   • ✗ Bypassing the 'isError' flag to prevent the coordinator from seeing transient network failures.

     Hooks should be used for data transformation and compliance enforcement, not for hiding critical error states that the coordinator needs for recovery.

   • ✗ Reducing the total number of tools the agent has access to by merging their output streams.

     Hooks transform the *result* of a tool call; they do not consolidate the tool definitions themselves or reduce the selection complexity.

9. 9 A third-party MCP server provides tool metadata including 'readOnlyHint': true. Your security policy requires user confirmation for any destructive action. How should this 'readOnlyHint' be architecturally treated?

   Can you trust a label provided by a system you don't own?

   As untrusted, self-reported metadata that should not be used as a primary security boundary for bypassing user confirmation.

   MCP annotations are hints provided by the server; unless the server itself is vetted and trusted, its self-reported labels cannot be relied upon for security.

   • ✗ As a cryptographic guarantee that the tool cannot perform 'WRITE' or 'DELETE' operations in the backend.

     A hint is merely natural language metadata and does not enforce system-level or database-level permissions.

   • ✗ As a signal that user confirmation is strictly required, as 'readOnlyHint' indicates high-risk data access.

     The hint suggests the *opposite*�that the action is safe and non-destructive�but the architectural risk lies in blindly trusting that suggestion.

   • ✗ As a mechanism to automatically allow the agent to bypass the 'isError' flag for that specific tool.

     The read-only status of a tool has no bearing on whether its execution results in a technical failure or error state.

10. 10 In the context of the Claude Agent SDK, an architect is deciding between using a 'PostToolUse' hook or a 'system prompt' instruction to enforce a rule that no refund over $500 should be processed. Why is the hook preferred?

    Which method is more 'guaranteed' in a software engineering sense?

    It provides a deterministic guarantee of compliance that does not depend on the model's probabilistic adherence to prompt instructions.

    Programmatic hooks enforce rules with 100% reliability at the code level, whereas models may occasionally ignore or hallucinate around prompt-based constraints.

    • ✗ It reduces the token footprint of the system prompt, lowering the cost of every request.

      While technically true, the primary architectural driver for hooks is reliability and security, not minor cost savings from prompt length.

    • ✗ It allows the agent to retry the refund with a smaller amount without the coordinator noticing the failure.

      Hiding policy violations from the coordinator prevents intelligent multi-agent orchestration and creates untraceable system behavior.

    • ✗ It enables the use of JSON schemas for the refund tool, which are not supported when using system prompt instructions.

      JSON schemas are part of the tool definition and are supported regardless of whether compliance is checked via prompts or hooks.

11. 11 Which built-in tool should be used if an agent needs to find every instance of a specific error code (e.g., 'ERR_702') across a codebase containing thousands of files in a nested directory structure?

    The model needs to look *inside* the files, not just at their names.

    Grep

    Grep is specifically designed for content-level pattern matching across file contents, making it the most efficient tool for finding strings in large repositories.

    • ✗ Glob

      Glob is used for file path pattern matching (finding files by name), not for searching the contents *inside* those files.

    • ✗ Read

      Read performs full-file operations and would require the model to sequentially read every file in the codebase, which is inefficient and context-heavy.

    • ✗ Bash

      While Bash can execute shell commands, built-in tools like Grep are optimized for specific developer workflows within the Claude ecosystem.

12. 12 An architect is splitting a generic 'manage_files' tool into three purpose-specific tools: 'read_config', 'update_source', and 'delete_temp'. According to Domain 2 principles, what must be updated to ensure the model routes correctly?

    The model relies on natural language to know which button to push.

    The tool descriptions must be rewritten to include explicit boundaries, examples, and contrastive logic for when to use each variant.

    Differentiating similar tools requires precise natural language descriptions that explain the unique purpose and constraints of each specialized interface.

    • ✗ The 'isRetryable' boolean must be set to 'false' for 'delete_temp' to prevent accidental data loss during a retry loop.

      Retry logic is an error-handling concern and does not address the model's fundamental challenge of selecting the correct tool for the task.

    • ✗ The transport layer must be switched from 'SSE' to 'stdio' to provide the model with lower-latency confirmation of its selection.

      Selection occurs at the reasoning layer before any transport takes place; latency does not influence the model's ability to differentiate tool purposes.

    • ✗ All three tools should be placed into a user-level configuration file (~/.claude.json) to prioritize them over project-level tools.

      Scoping does not solve selection ambiguity; tools from all configured levels are discovered and presented simultaneously, which might actually increase overload.

13. 13 A multi-agent research pipeline fails when a subagent encounters a 404 error while fetching a URL. The subagent returns an empty list to the coordinator. Why is this considered an architectural anti-pattern?

    What happens if the 'brain' of the system thinks everything is fine, but data is actually missing?

    It suppresses a technical failure as a successful empty result, preventing the coordinator from making informed recovery decisions.

    Silently suppressing errors hides critical context; the coordinator needs to know *why* the result is empty to decide whether to try an alternative source or retry.

    • ✗ Empty results should always be marked with 'isRetryable': true to ensure the model keeps trying until it finds data.

      If a page truly doesn't exist (404), retrying is useless; the error should be categorized so the system can change its strategy instead.

    • ✗ Subagents should never handle their own local error recovery; all exceptions must be propagated immediately to the top-level handler.

      Domain 2 actually suggests subagents *should* implement local recovery for transient failures and only propagate unresolved issues.

    • ✗ Returning lists is context-inefficient; subagents should always return raw binary streams to the coordinator.

      LLMs reason over text and structured data; binary streams are unreadable to the model and would require an additional parsing step.

14. 14 In an MCP tool definition, a parameter 'query_type' is defined as a string. How can an architect use Domain 2 'Tool Design' techniques to most effectively reduce hallucinated inputs?

    Think about how you'd restrict a user in a web form to only a few choices.

    Use a strictly defined 'enum' in the JSON schema to limit the model to a list of allowed values.

    Enums provide a structural constraint that the model must follow, effectively eliminating the possibility of it generating a value outside the supported set.

    • ✗ Write a long paragraph in the system prompt begging the model not to invent query types.

      Prompt engineering is probabilistic; structural schema constraints are far more reliable for enforcing specific input values.

    • ✗ Implement a 'PreToolUse' hook that guesses what the model meant if it provides an invalid string.

      Guessing introduces non-deterministic behavior and risks corrupting the data; it's better to prevent invalid input or return a validation error.

    • ✗ Switch the tool to the Message Batches API to allow for human review of every query type before execution.

      The Batch API is for high-volume asynchronous tasks and does not solve the underlying design issue of model-driven hallucinations.

15. 15 An agent needs to search a large internal document catalog via an MCP tool. To prevent 'context bloat' and 'lost-in-the-middle' effects, which tool parameter design is best?

    How do web APIs handle thousands of search results?

    Implement programmatic cursor pagination by returning a 'next_cursor' and total match count.

    Pagination allows the model to process data in manageable chunks, maintaining high retrieval accuracy and avoiding context window exhaustion.

    • ✗ Configure the tool to automatically return the full content of the first 100 matching documents in one response.

      Dumping massive amounts of content into the context window causes performance degradation and high token costs.

    • ✗ Use the 'max_tokens' parameter to truncate the tool output string after 2,000 characters.

      Silent truncation hides information and may cut off data in the middle of a structured JSON block, causing parsing failures.

    • ✗ Force the model to call a separate 'summarize_page' tool for every individual document found.

      Individual calls for every document significantly increase latency and cost; pagination provides a better balance for discovery.

16. 16 You are building an agentic loop and need to determine when to stop the iterations and present the final result to the user. Which signal should the application monitor?

    Look for a specific technical field returned by the Claude API that manages control flow.

    The 'stop_reason' value in the API response being 'end_turn'.

    In the standard agentic loop, 'end_turn' indicates the model has finished its reasoning and action sequence and is ready to deliver its final response.

    • ✗ The presence of natural language phrases like 'I have finished the task' in the assistant text.

      Parsing natural language is unreliable and prone to false positives; technical flags like 'stop_reason' provide a deterministic signal.

    • ✗ Reaching an arbitrary cap of 10 iterations as the primary termination mechanism.

      Iteration caps are safety guardrails, but they are not indicators of task completion; they may cut off the agent before the goal is reached.

    • ✗ The 'isError' flag on the last tool call being set to 'false'.

      A successful tool call ('isError': false) usually means the loop should *continue* so the model can process the result, not that the entire task is done.

17. 17 A developer wants to ensure that a coordinator agent and its subagents can all access a custom 'internal_wiki' MCP server. Where should this server be configured for a shared team environment?

    How do you share configurations across a distributed team using version control?

    In a project-scoped '.mcp.json' file included in the code repository.

    Project-scoped configuration ensures that all team members (and their agents) share the same toolset and can collaborate using consistent interfaces.

    • ✗ In each individual developer's user-scoped '~/.claude.json' file.

      User-level settings are personal and not shared via version control, which would lead to inconsistent behavior and 'it works on my machine' errors.

    • ✗ Within the 'CLAUDE.md' instructions of every subdirectory in the project.

      CLAUDE.md is for natural language instructions and conventions; it is not the mechanism for defining MCP server connection parameters.

    • ✗ Hardcoded directly into the Agent SDK 'AgentDefinition' objects for each subagent.

      While possible, it duplicates configuration and makes the system harder to maintain compared to using a centralized MCP configuration file.

18. 18 When designing an MCP tool, an architect adds a parameter 'is_confirmed' with a default value of 'false'. During testing, the agent frequently omits this parameter entirely. How should the JSON schema be improved?

    Which JSON schema property ensures a key must be present in the output?

    Include 'is_confirmed' in the 'required' fields list of the tool schema.

    Explicitly marking fields as 'required' in the schema forces the model to include them, preventing errors caused by missing mandatory inputs.

    • ✗ Add a comment in the parameter description saying 'Please don't forget this!'.

      Comments in descriptions are helpful but less authoritative than the structural 'required' flag in the JSON schema itself.

    • ✗ Rename the parameter to 'MANDATORY_is_confirmed'.

      Renaming can sometimes help with selection but does not enforce the presence of the field in the generated payload.

    • ✗ Use a 'PostToolUse' hook to inject 'false' whenever the parameter is missing.

      While a hook can fix the payload, it doesn't solve the underlying issue of the model not understanding that the field is mandatory for its reasoning.

19. 19 A multi-agent system uses a 'synthesis_agent' to combine findings from three search agents. The synthesis agent occasionally attempts to perform its own web searches, which it is not designed to do. What is the best remediation?

    If you don't want someone to use a tool, don't give it to them.

    Configure the synthesis agent's 'allowedTools' to exclude any web search tools, applying least-privilege principles.

    Limiting tool access to only those relevant to an agent's role prevents misuse and reduces the cognitive load of selecting from irrelevant tools.

    • ✗ Update the synthesis agent's system prompt with a warning: 'Do not attempt to search the web'.

      Negative constraints in prompts are less reliable than technical restrictions at the SDK or API configuration level.

    • ✗ Increase the 'max_tokens' for the synthesis agent to allow it to handle the extra reasoning turns for searching.

      Enabling the misuse doesn't fix the architectural problem; it likely increases costs and latency for a task the agent wasn't meant to perform.

    • ✗ Implement a 'PreToolUse' hook that redirects search calls back to the coordinator agent.

      Redirecting calls is a reactive fix; preventing the model from seeing the tools in the first place is a more robust proactive design.

20. 20 In Domain 2, 'Tool Design' emphasizes 'idempotency'. Which scenario describes an architect correctly applying this principle to an MCP tool?

    Think about what happens if a tool call is sent twice because the first one timed out.

    Designing a 'create_incident' tool that takes a 'client_request_id' to prevent duplicate tickets if the agent retries a failed call.

    Idempotency ensures that performing the same operation multiple times has the same effect as performing it once, which is critical for reliability in retry-heavy agentic systems.

    • ✗ Ensuring that the 'get_inventory' tool returns a random sample of items to provide the model with varied context.

      Randomness is the opposite of idempotency; idempotent tools should return consistent results for the same inputs.

    • ✗ Configuring the 'delete_user' tool to automatically back up data before every execution.

      Backups are a safety feature, but they don't ensure that repeating the delete operation multiple times is safe or has a consistent outcome.

    • ✗ Designing a 'sum_values' tool that clears its local cache after every five seconds.

      Cache clearing is a memory management concern and does not address the fundamental logic of the tool's interface or side effects.