Document Lambda event contract for Gateway Lambda targets (bedrockAgentCoreToolName)

[markproy]

Problem

The agentcore-gateway.md reference shows how to create a Lambda target with inline tool schema, but does not document the Lambda invocation contract — specifically what the Lambda receives as event and context when Gateway invokes it.

This leads to a common failure pattern:

1. Developer defines multiple tools pointing at one Lambda
2. Developer writes Lambda expecting event.get("name") to contain the tool name
3. Lambda receives only the bare arguments (e.g. {"a": 1, "b": 2}) — no tool name in the event
4. All tools return "unknown tool" errors
5. Developer iterates blindly until discovering the undocumented mechanism

Actual Behavior

The Gateway passes the tool name via the Lambda client context, not the event payload:

tool_name = context.client_context.custom.get('bedrockAgentCoreToolName', '')

This is only documented in the starter toolkit quickstart guide's example code, not in the skill's reference file that Claude Code agents use when building Gateway integrations.

Suggested Addition

Add a "Lambda Event Format" section to the Gateway reference with:

1. Event payload: Contains only the tool's arguments (the input schema values), not wrapped in any envelope
2. Tool name: Available at context.client_context.custom['bedrockAgentCoreToolName']
3. Expected response format:

{"content": [{"text": "..."}]}

or for errors:

{"content": [{"text": "..."}], "isError": true}

Example Lambda handling multiple tools

import json

def lambda_handler(event, context):
    tool_name = context.client_context.custom.get('bedrockAgentCoreToolName', '')
    
    if 'add' in tool_name:
        result = event['a'] + event['b']
    elif 'multiply' in tool_name:
        result = event['a'] * event['b']
    else:
        return {"content": [{"text": f"Unknown tool: {tool_name}"}], "isError": True}
    
    return {"content": [{"text": json.dumps({"result": result})}]}

Impact

Without this, every developer building a multi-tool Lambda target will waste significant time debugging the same issue. This is the #1 thing you need to know when writing a Gateway Lambda handler, and it's completely absent from the reference that AI coding assistants use.