Replace arbitrary fetching with validated loading

Learning objective

Replace overly broad tools with constrained operations, such as a validated document loader rather than arbitrary URL fetching.

Core idea

A broad tool delegates a large decision space to the agent. A generic fetch_url operation asks Claude to select a destination and assumes your implementation can safely retrieve it. A constrained load_document operation asks for an approved document and makes destination validation part of execution.

These names describe application-defined client tools. Anthropic does not supply the document registry or access policy in this example. The Messages API supplies the interface: you declare the operation through tools, Claude requests it through a tool_use block, and your application executes the request and returns a tool_result.

The architectural improvement comes from changing the capability, not its label. Renaming arbitrary fetching to load_document while accepting every destination preserves the original authority. A constrained operation removes choices the specialist does not need and makes its intended use easier to distinguish from general research.

How it works

Define the operation the task needs

Anthropic’s tool-design guidance recommends a few thoughtful tools targeting high-impact workflows, with clear and distinct purposes. Apply that guidance to document retrieval: expose an operation that returns usable document evidence, rather than exposing every low-level network function used to obtain it.

Suppose a research specialist receives a set of approved policy documents. The load_document definition uses name to identify the operation, description to explain its approved scope, and input_schema to describe the parameters. A document_url string can carry the requested URL when that is the identifier used by the workflow. The implementation then validates it against the approved registry.

An alternative is a document_id parameter that the implementation resolves to a stored destination. Choose this when the agent already receives stable document identifiers and does not need to reason about URLs. That design removes destination selection from the model’s task instead of asking it to reconstruct a trusted address.

If a task has a small fixed set of documents, an enum in input_schema can express the allowed identifiers. If the set changes with the request, the runtime registry is the decisive check. See 0.3 for the schema’s treatment of property presence and nullability; schema shape does not establish resource authorization.

Keep selection guidance and validation separate

The description should explain when to use the loader, what counts as an approved document, what content it returns, and what happens when the requested document is unavailable. Anthropic recommends detailed descriptions, including caveats and cases where a tool should not be used. That information helps Claude select the correct operation.

The loader implementation enforces the actual scope. In this application, it resolves the requested URL or identifier against the request’s approved documents, checks that the caller may load the resolved document, and retrieves only the permitted content. Treat this registry check as part of the custom tool’s contract, not as a claimed Anthropic API feature.

If a document redirects, the custom loader checks the resolved destination against the approved set and returns an error when it cannot establish permission.

Do not let the agent supply an approved: true argument as proof of authorization. That would put the decision back into model-generated input. The trusted registry and execution context determine approval; the tool input identifies what the model wants to load.

Return evidence or an actionable error

For client tools, your application reads tool_use.name, tool_use.id, and tool_use.input and dispatches to the corresponding implementation. A successful loader returns the document content and the attribution needed for the research task. Anthropic recommends high-signal tool responses rather than bloated intermediate data.

A rejected or unavailable document returns a tool_result with the matching tool_use_id, is_error: true, and an explanation in content. For example, the explanation can say that the requested document is outside the approved registry and identify the permitted way to request additional evidence. Avoid returning a generic error that encourages repeated guesses at URLs. Every check the loader runs ends in permitted content or in a matching error result.

Preserve the protocol’s correlation even when execution is rejected. A failed validation is still a result for the requested call. See 1.1.2 for message ordering and matching; this lesson focuses on what the loader permits, rather than rebuilding the conversation loop.

Scope Anthropic’s web fetch tool

When a role needs broader web retrieval on the Claude API, Anthropic’s web_fetch server tool offers destination and usage controls. Use allowed_domains to restrict fetching to known domains and max_uses to limit fetches per request. Failed fetches count toward that limit. Alternatively, blocked_domains excludes named domains; you cannot combine it with allowed_domains.

The tool fetches only URLs that previously appeared in user messages, client-side tool results, or earlier web search or web fetch results. A URL appearing only in Claude’s own output or only in the system prompt is not eligible. This conversation-context rule constrains fetching; it does not prove that a document is authorized for the specialist.

Domain allowlisting also permits more than an exact document set: another page on an allowed domain can remain in scope. Give a role that should read only approved documents the custom load_document operation instead. Server-tool controls narrow web retrieval, while the loader’s trusted registry enforces document-level validation.

Key distinctions and trade-offs

Constrained operation versus renamed wrapper: A constrained loader checks permitted documents and limits what it retrieves. A wrapper with the same unrestricted destination parameter merely hides the breadth behind a friendlier name.

Input contract versus execution authority: input_schema tells Claude which values form a valid request. Runtime authorization decides whether the identified resource is permitted for this caller. A well-formed URL can still identify an unauthorized document.

Workflow convenience versus flexibility: A loader can resolve an identifier and return content with attribution in one call. It is less flexible than a generic fetcher, which is useful when the specialist’s assignment is deliberately narrower than open-ended browsing.

Missing evidence versus expanded privileges: A registry rejection can reveal that the coordinator supplied an incomplete evidence set. Repair the assignment or approve a separate research task; do not turn every failed lookup into permission to fetch any URL.

Architecture / decision scenario

A multi-agent research system asks a specialist to compare three approved policy documents. Its existing fetch_url tool accepts any URL. When a cited document is missing, the specialist guesses another address and retrieves material outside the approved collection.

The architect replaces that entry in the specialist’s Messages tools array with load_document. Its description says it loads approved policy documents and does not perform open-ended discovery. The input_schema identifies document_url as the required request field. The application’s loader resolves that URL against the approved registry before retrieval and checks any resulting destination against the same policy.

For an approved URL, the loader returns relevant document content with source attribution. For an unapproved URL, it returns a matching tool_result with is_error: true and a concrete scope explanation. The specialist includes the evidence gap in its handoff; the coordinator decides whether to commission additional research.

The team evaluates both allowed and rejected requests. It checks that useful documents still load, that unknown destinations never reach the retrieval implementation, and that error explanations guide the agent toward the permitted path. The change reduces arbitrary destination selection while preserving the researcher’s legitimate document-reading capability.

Common exam traps

• Renaming fetch_url without changing what destinations execution permits.
• Treating a valid string or URL as proof of document authorization.
• Putting approval in a model-supplied boolean instead of trusted runtime state.
• Returning an uncorrelated error instead of a matching tool_result.
• Falling back to arbitrary fetching when registry validation fails.
• Exposing low-level network choices the document task does not require.

What to remember

Expose the operation that fulfills the role’s task. Use name, description, and input_schema to make it selectable, then enforce approved resources inside the client-tool implementation. Return useful evidence or an actionable is_error: true result. Constraining the capability means removing unnecessary authority, not changing its name.

Knowledge check

References

• Anthropic, Define tools
• Anthropic, Web fetch tool
• Anthropic, Handle tool calls
• Anthropic, Writing effective tools for agents