A&A INSIGHTS
Customer APIs As-Is or Task-Specific Tools? Decide Before Estimating
Before estimating AI-agent development, decide where customer APIs can remain as-is and where task-specific tools must be built, then price the redesign as its own workstream.
日本語で読む
THE STARTING POINT
Decide tool scope before estimating: keep an existing API where its operation already matches a safe, observable step; build a task-specific tool where the agent must combine several operations, shape results, or manage exceptions. Price that rebuild as a separate deliverable, and narrow the task when the customer’s API, authentication, or permissions do not allow a new tool.
Decide the Tool Granularity, Not Just the Model
A&A perspective
When a customer supplies a list of existing APIs, do not begin by treating each endpoint name as a tool definition. A&A proposes writing one business definition for each workflow: what triggers it, who makes the decisions, which inputs are used, and who checks the output. From that definition, decide for each step whether to call the existing API directly, add a thin adaptation layer, or build a consolidated tool around the business task. This keeps work discovered during implementation from falling outside the estimate.
From the sources
Anthropic says the most successful implementations it observed used simple, composable patterns rather than complex frameworks or specialized libraries. It recommends tailoring capabilities to the use case and providing an easy, well-documented interface for the LLM. It also places careful design of the agent-computer interface through thorough tool documentation and testing among its core principles.
A&A perspective
Tool granularity is the boundary between one business step on the agent side and the underlying system operations. A single outcome may require several APIs, while one API may support several workflows. The practical choice is therefore not one global policy. For each step, separate the cases where a direct call is sufficient from those that need consolidated context, call sequencing, or response shaping. This is A&A’s interpretation, not a universal requirement established by Anthropic.
Draw the Boundary Around a Unit of Human Work
A&A perspective
A&A’s proposed business definition sheet records the trigger, inputs, permissions, human decision points, call sequence, escalation path for exceptions, and completion condition. It follows how an operator currently reaches one decision rather than how the customer’s systems are arranged. Instead of writing only customer handling or renewal processing, identify the information required, the decision that needs a person, and the state at which the work is ready for confirmation.
From the sources
Anthropic says tools for agents must be designed for agents rather than written in the same way as functions and APIs for other developers or systems. It characterizes a tool as a contract between deterministic systems and non-deterministic agents whose responses can vary.
Hypothetical example
Consider a fictional example: preparing a customer renewal quote. If an operator currently identifies the contract, checks usage, consults discount rules, and attaches exceptions, that sequence is one human work unit: creating a renewal proposal. Even if the customer exposes APIs for contract retrieval, usage listing, and price calculation, the tool scope depends on whether the operator coordinates those calls or the agent does. This example is fictional and does not represent an actual customer or outcome.
When an Existing API Can Remain Thin
From the sources
Anthropic says more tools do not always produce better outcomes. It identifies tools that merely wrap existing software functions or API endpoints, whether or not those tools suit agents, as a common error. Its recommendation is to build a smaller set of thoughtful tools for specific, high-impact workflows that match the evaluation tasks.
A&A perspective
A&A treats direct use of an existing API as a candidate when each operation already corresponds to a safe business step, call ordering and failure recovery can be defined elsewhere, the request can express the required filtering, and the response can remain limited to what is needed. The existence of an endpoint is not enough by itself. Anthropic does not state that every API wrapper is inherently wrong.
A&A perspective
Even with direct calls, do not hide the thin adaptation layer from the estimate. Separate connection and authentication, request and response mapping, permission constraints, error behavior, logging, and verification by scope and condition. An existing SDK, specification, or test environment may reduce some work, but none of the source articles provides a fixed reduction. A&A proposes estimating the customer’s actual work rather than applying a generic source ratio.
Rebuild the Tool Around the Business Task
From the sources
Anthropic says a tool can consolidate multiple discrete operations or API calls under the hood. As an example, it suggests combining availability lookup and event creation in a single schedule_event tool rather than exposing separate list and create operations.
From the sources
Anthropic says tools should let agents subdivide and solve tasks much as a human would with the same resources, while reducing the context otherwise consumed by intermediate outputs. Its examples include search_logs instead of read_logs, and get_customer_context instead of several separate customer-data operations.
A&A perspective
Anthropic’s examples make response shaping and consolidation legitimate design work. Existing raw responses do not automatically have to be replaced, but when a business decision requires reading several large responses, selecting meaning, and choosing an order, the response boundary and operation consolidation should be evaluated. A rebuild estimate should define the business purpose, inputs, call sequence, pagination or filtering defaults, output, and stop conditions. This is A&A’s synthesis, not a guarantee that call counts will always fall.
Choose Granularity and Scope Task by Task
A&A perspective
A&A’s comparison table contains the business outcome, the unit a person would normally complete, the existing APIs, agent decisions, exception handling, selected granularity, deliverables, and verification method. Rows follow business steps rather than systems or endpoints. For each row, choose a direct call, a thin adaptation layer, or a business-specific tool, and record why the selected granularity fits.
Hypothetical example
In the fictional renewal example, customer search can remain a direct-use candidate if the existing search returns what is required. For usage verification, a thin adaptation layer or a dedicated search tool may be appropriate if the existing API needs date and product filtering. For proposal creation, if a person assembles contract data, usage, discount rules, and exceptions, the rebuild becomes a separate task-specific tool item. The same project can therefore contain all three choices.
A&A perspective
There is no need to replace every API with a specialized tool, nor to keep every API at the lowest level. Anthropic warns that too many tools, or tools with overlapping or vague purposes, can distract agents. A&A proposes comparing call order, state, exception handling, sensitive information, and observability for each step, then building a consolidated tool only where the workflow needs it.
Price the Rebuild as Its Own Estimate Item
From the sources
Anthropic describes building a quick tool prototype, testing it locally, running a comprehensive evaluation, and repeatedly improving the tool from the observations. Its evaluation metrics include total runtime, the number of tool calls, token consumption, and tool errors.
A&A perspective
A&A proposes separating the estimate into requirements and workflow mapping; authentication and permissions; thin adaptation to existing APIs; construction of a task-specific tool; response shaping and exception handling; and evaluation, testing, documentation, and handover. Items three and four should remain separate even if they occur in the same sprint. When the tool is necessary for the deliverable, item four is a required workstream. A&A does not provide a standard number of days or percentage.
A&A perspective
Use item names such as thin adaptation to existing APIs and construction of a business-specific tool rather than placing everything under API connection. For the latter, state the included workflow, inputs, permissions, shaped output, exception behavior, and verification method. The rebuild is not an optimization allowance; it is the work required to deliver the selected tool. If the workflow or permissions change after approval, re-estimate only the affected steps.
When Constraints Exist, Narrow the Scope
A&A perspective
The two Anthropic articles are technical design guidance, not standards for service estimates, contracts, margins, win rates, or estimating accuracy. A&A’s decision to itemize the rebuild is a business translation, not a pricing or contracting recommendation from Anthropic. Experiences from a specific internal setting such as SWE-bench are not a general ratio. A&A proposes estimating from the customer’s APIs, permissions, trial tasks, and assigned scope rather than from invented standard days or percentages.
A&A perspective
If the API cannot be changed and authentication or permissions permit only a thin layer, A&A does not assume that rebuilding is possible. First limit the agent to a safe single operation and leave call ordering or exceptions with the human workflow. If the task includes writes or permission changes, name the confirmer and stop condition. Explaining the constraint is not the same as preserving a specialized-tool scope that cannot be implemented.
A&A perspective
Before sending the estimate, A&A recommends answering eight questions for each workflow: the desired outcome, human decision points, whether the API can change, call order, permissions and sensitive data, exception recovery, evaluation method, and confirmer. If the result is direct use of an existing API, document only the required connection scope. If several operations must become one business capability, create a separate rebuild item. In both cases, put the rationale and exclusions next to the choice.
Whether to keep customer APIs as they are or rebuild task-specific tools is a scope decision, not merely an implementation choice. Map the human work, API constraints, exceptions, and verification method first. When rebuilding is necessary, price it as a deliverable separate from connection work.
Sources & editorial note
Primary pages read for this article. Publication dates below belong to the sources; access dates record our research.
- Building effective agents
Anthropic · 2024-12-19
Accessed 2026-10-04 - Writing effective tools for AI agents
Anthropic · 2025-09-11
Accessed 2026-10-04
AI-assisted editorial production
A&A uses AI for research, writing, translation and editorial checks. Source facts, our analysis and hypothetical examples are labeled separately.
Editorial check: 2026-10-04