Design an agent around bounded, observable actions

Choose the right amount of autonomy

Anthropic’s agent architecture guidance distinguishes fixed workflows from systems in which a model chooses the next steps and tools. That distinction is useful when designing an integration: predictable routing and open-ended investigation need different controls.

Start by listing the decisions the application already knows how to make. Keep those in ordinary code. Reserve model judgment for the parts where interpreting changing context adds value, such as selecting which approved document to inspect next.

Design each action like an API

A tool description should tell the model what the action does, when it is appropriate, which inputs it accepts, and what success looks like. Use narrow names such as “read invoice summary” instead of a catch-all “manage account” function. Separate retrieval from operations that change records or contact people.

• Inputs: Require unambiguous identifiers and validate arguments.
• Permission: Check the acting user’s access in the execution layer.
• Result: Return a stable status and the evidence needed for the next step.
• Limits: Bound time, repeated attempts, and the number of actions.

A model-generated tool call is a proposal for the application to process. It is not proof that the action is allowed or has occurred. Record the actual execution result before marking a task complete.

Make failure recoverable

Consider a documentation agent that reads an API reference and drafts an integration note. If a document is unavailable, it should preserve what it learned, identify the missing evidence, and stop or request a narrower input. Repeating the same failed retrieval indefinitely adds no useful progress.

Store enough information to review a run: the user’s objective, the approved tools, relevant inputs, action outcomes, and the final artifact. Redact secrets from those records. Use this evidence to distinguish a reasoning error from a bad tool definition or a provider outage.

Explore MCP’s tool and context model when connecting an AI application to external systems. Use API security test planning to examine permission checks at each execution boundary.