Skip to lesson

AnthropicClaude Certified Architect – Foundations2026-102.1 Design effective tool interfaces with clear descriptions and boundaries

Choose tool granularity by the outcome

Completed by the knowledge check

Learning objective

Choose between splitting over-general tools into narrow operations and consolidating genuinely redundant tools.

Core idea

Choose a tool surface that makes the requested outcome identifiable without forcing Claude to navigate artificial distinctions. One generic tool can hide unrelated responsibilities. Many small tools can present duplicate choices or expose implementation steps that the application could perform together.

The CCAR-F exam guide illustrates splitting the application tool analyze_document into extract_data_points, summarize_content, and verify_claim_against_source; these names are design examples, not Anthropic built-ins. The API’s tool-definition guidance also recommends consolidating related operations into fewer tools, using an action parameter when appropriate. These recommendations address different defects: unclear responsibility within an operation and unnecessary ambiguity among operations.

As an architect, choose granularity from the task contract rather than a rule that every tool must be tiny or every service must expose one tool. The decisive question is whether an operation represents a coherent outcome with understandable inputs and outputs. See 2.1.1 for description coverage and 2.1.2 for diagnosing overlapping names.

How it works

Split an operation that hides distinct outcomes

Suppose analyze_document accepts document_id and an unrestricted instruction string. Depending on that instruction, it extracts values, writes a summary, or assesses whether a claim is supported. A description promising “document analysis” does not establish which kind of result a caller receives.

The exam guide’s split makes those outcomes visible. extract_data_points accepts a document identifier and requested fields. summarize_content accepts a document identifier and the focus of a narrative summary. verify_claim_against_source accepts a document identifier and a claim to compare with source passages. Each tool has its own name, description, and input_schema in the Messages API tools array.

Define the corresponding output contracts. In this example, extraction returns field records, summary returns an overview, and verification returns a supported comparison with evidence. The result contracts explain why the operations divide: a narrative overview cannot substitute for extracted fields or a claim-specific comparison.

Splitting is valuable when the caller needs to select these outcomes independently. It also removes the need to explain several unrelated input conventions under one free-text parameter. The purpose is clearer selection and contract meaning, not a guarantee that the model cannot make mistakes.

Consolidate choices that do the same work

Now suppose get_document_overview and summarize_document accept the same identifier, invoke the same implementation, and return equivalent narrative summaries. Their different names create a choice without a meaningful difference. Consolidate them into one exposed operation whose description covers the supported use cases.

Compare contracts before declaring redundancy. Two similarly named searches might access different repositories or return different evidence. If source identity matters, preserve it through a clear resource or service namespace rather than merging it away. Anthropic recommends meaningful namespacing where multiple services or resources have similar operations.

Consolidation also applies to closely related actions on one resource. Anthropic’s API documentation gives the example of grouping create_pr, review_pr, and merge_pr behind an action parameter instead of exposing a separate tool for every action, because fewer, more capable tools reduce selection ambiguity. This is a recommendation for a coherent tool surface, not a statement that every group of verbs should share a contract.

For a consolidated interface, input_schema.properties.action can define the accepted action values with an enum. Explain each value’s meaning and relevant arguments in the schema and description. A finite action selector is clearer than an unrestricted string instructing an all-purpose tool to do anything. Keep each action’s actual behavior and result interpretation explicit.

Consolidate a coherent workflow inside the tool

Another form of consolidation combines implementation steps that callers routinely need together. Anthropic’s engineering guidance proposes get_customer_context instead of separate tools for customer lookup, transactions, and notes. It also proposes schedule_event for finding availability and scheduling an event.

These examples expose a useful outcome rather than every backend API call. The tool implementation performs the related work and returns relevant information. This reduces intermediate material Claude must process, while keeping the externally visible responsibility understandable.

Do not equate workflow consolidation with dumping all available data into one result. Anthropic contrasts retrieving every contact with searching for relevant contacts, and recommends high-signal tool responses. A consolidated customer-context tool should return the context needed for its documented task, not an unfiltered archive because several endpoints are available underneath it.

Likewise, combining summary, extraction, and verification is justified only if the exposed outcome genuinely requires that combination and the contract explains it. Combining them merely to reduce the tool count recreates the ambiguous analyzer from the first example.

Evaluate the operation boundary

Use the evaluation method in 2.1.2 to compare the proposed surfaces. Here, check whether splitting adds redundant calls or consolidation drops required evidence. The smaller tool count is a design characteristic, not the success criterion.

For a split, check whether requests map to distinct outcomes without redundant calls. For consolidation, check whether one operation preserves all required evidence and avoids irrelevant output. Include compound tasks and tasks requiring only one part of the proposed combined operation.

Evaluate results as well as selection. A consolidated operation that executes fewer calls but omits source passages fails a task needing attribution. A split that produces three calls when a user only requested an overview might impose unnecessary work. The appropriate boundary is the one that preserves the required outcome while making the interface easier to use.

Key distinctions and trade-offs

Narrow responsibility versus tiny implementation: One tool can invoke several backend endpoints and still have one clear purpose. Endpoint count does not define tool responsibility.

Redundancy versus relatedness: Duplicate summary tools are redundant. Extraction and verification are related through a document but produce distinct outcomes. Related operations can share an action-based interface only when that contract remains clear. The test is whether a call states what it will do: an action enum names the operation, while an unrestricted instruction leaves Claude to infer the mode from wording. Split when one schema cannot keep each mode’s arguments and result explicit, as with the free-text instruction of analyze_document.

Selection count versus input complexity: Splitting adds exposed choices but can simplify each schema. Consolidation reduces exposed choices but can complicate action-specific arguments. Inspect both sides of the decision.

Consolidation versus output bloat: Returning useful combined context can save intermediate calls. Returning everything can consume context and obscure the answer. The response must remain aligned with the purpose.

Architecture / decision scenario

A structured-data extraction assistant exposes a generic analyze_document, two equivalent summary tools, and separate lookup tools for contract metadata and document ownership. Users ask for extracted renewal dates, narrative summaries, and verification of cancellation claims.

The architect splits the generic analyzer into the exam guide’s three illustrative outcomes. Each tool’s input schema and description match the requested result. They consolidate the two equivalent summary tools into the single narrative operation, so the split does not preserve redundant alternatives.

For recurring requests that need document metadata and ownership together, they consider a get_document_context operation. Its implementation combines the related lookups and returns only the relevant context. Requests needing claim evidence still use the verification contract; context lookup does not silently become analysis.

The evaluation includes an extraction-only request, a summary-only request, a claim comparison, and a compound request. It checks returned fields and supporting evidence as well as call counts. The chosen interface succeeds by making each required outcome clear, removing duplicate choices, and combining coherent lookup work without creating another all-purpose analyzer.

Common exam traps

  • Applying “split every tool” as an unconditional rule.
  • Preserving duplicate tools because their names differ.
  • Consolidating unrelated outcomes behind an unrestricted instruction parameter.
  • Treating fewer tool calls as success when required evidence disappears.
  • Exposing every backend endpoint as a separate model-facing tool.
  • Assuming an action selector removes the need to document action-specific inputs and outputs.

What to remember

Split when a generic operation hides independently meaningful outcomes. Consolidate when exposed choices are redundant or a coherent workflow can return the useful result directly. Choose the boundary through clear contracts and outcome-based evaluation, not tool count alone.

Knowledge check

References