Skip to main content

Tool Design & Gateway for Workflow Agents

Who this is for

Builders designing tools and connecting them via the AgentCore Gateway for a workflow agent. If you haven't wired up event sources yet, see Event Processing first.

Tools are the hands of the agent. Well-designed tools make the difference between an agent that works and one that hallucinates actions.

Tool Design Principles​

PrincipleWhy
One tool = one actionCompound tools confuse the LLM. Split "get and update" into two tools.
Descriptive names and docstringsThe LLM decides tool selection based on name + description. Be specific.
Validate all inputsThe LLM sends arbitrary values. Check types, formats, and bounds.
Return errors as valuesDon't raise exceptions. Return {"error": "..."} so the agent can adapt.
Typed schemasEvery tool gets a JSON schema defining inputs. No "catch-all" parameters.
Idempotent where possibleAgent might retry on failure. Make tools safe to call multiple times.

Example: Well-Designed Tool​

@tool
def get_incident_details(incident_id: str) -> str:
    """Retrieve full details for an incident by its ID.

    Call this tool when you need to understand the current state,
    severity, affected services, and timeline of an incident.

    Args:
        incident_id: The incident identifier (format: INC-NNNNN).
    """
    if not incident_id or not re.match(r"^INC-\d{3,7}$", incident_id):
        return "Error: incident_id must match format INC-NNNNN"

    try:
        item = incidents_table.get_item(Key={"id": incident_id}).get("Item")
        if not item:
            return f"Error: Incident {incident_id} not found"
        return json.dumps(item, default=str)
    except Exception as exc:
        return f"Error: {type(exc).__name__}: {exc}"

Tool Hosting: Co-Located vs. Gateway​

ApproachWhen to UseTrade-off
Co-locatedSimple tools, few dependencies, fast iterationNo separate deployment or IAM
Gateway targetComplex or shared tools, many tools, cross-agent reuseMore infrastructure, more reuse

MCP Gateway​

The Gateway aggregates all MCP targets into a single virtual MCP server, exposing one consolidated tools/list to the agent. Semantic tool search lets the agent select the right tool even when hundreds are registered. This is important for autonomous workflows that span many enterprise systems. See the Gateway quick start for step-by-step setup.

The default quota is 100 targets per gateway and 1,000 tools per target, both adjustable via Service Quotas. See the AgentCore quotas reference for the full set of Gateway limits.

Target TypeUse For
Lambda functionCustom business logic in any language; gateway invokes and maps to MCP
OpenAPI / API GatewayTurn an existing REST API into MCP tools with no code
Smithy modelGenerate tools for AWS services or Smithy-defined APIs
MCP serverConnect a remote MCP server's tools, prompts, and resources
Integrations / connectorsPre-built templates and connectors for common tools
Beyond tools

The Gateway supports three target categories. MCP targets (listed above) are aggregated into the virtual MCP server. HTTP targets proxy directly to other agents or A2A services, which is useful when a workflow agent orchestrates specialized sub-agents. Inference targets route LLM traffic to multiple model providers through one endpoint. The main table above covers MCP targets; consult the Gateway documentation for HTTP and Inference target configuration.

Authentication Model​

The Gateway separates the two directions of authentication, which matters for autonomous agents that run without a human in the loop:

  • Inbound (agent → gateway): use IAM (SigV4) so the agent calls as a service identity. OAuth (JWT) is also supported; authenticate-only validates the token but defers authorization to the target.
  • Outbound (gateway → backend): Lambda and Smithy targets use the gateway's execution role; OpenAPI and MCP-server targets use an AgentCore credential provider (API key, OAuth, or SigV4), so credentials for Jira, ServiceNow, or internal APIs stay in the gateway rather than the agent.

Managed Tool Access​

Managed Tool Access via MCP Gateway

Connect agents to internal APIs, databases, ticketing systems, and cloud infrastructure through a managed MCP gateway. Targets can be Lambda functions, OpenAPI or Smithy APIs, or remote MCP servers. The gateway aggregates them into one virtual MCP server with semantic tool search, so the agent finds the right tool even across hundreds. Inbound access is secured with IAM (SigV4) or OAuth; outbound calls to each backend use a managed credential provider so secrets never live in the agent.

Gateway

Further Reading​