rohitg00/ai-engineering-from-scratch · warning · ValueError

choose one execution boundary for a capability

Error message

choose one execution boundary for a capability

What it means

choose_capability_surface raises ValueError('choose one execution boundary for a capability') when more than one of the three execution-surface flags is set: shared_standard_service, provider_executed_builtin, anthropic_schema_client_tool. It enforces that a capability has exactly one place where code executes; mixing boundaries is a design contradiction the function refuses to guess about.

Source

Thrown at certifications/claude/lessons/10-tool-use-and-agentic-loops/code/main.py:63

class CapabilityNeeds:
    """Separate executable capability from optional reusable procedure."""

    reusable_procedure: bool = False
    shared_standard_service: bool = False
    provider_executed_builtin: bool = False
    anthropic_schema_client_tool: bool = False


def choose_capability_surface(needs: CapabilityNeeds) -> dict[str, str]:
    execution_flags = sum(
        (
            needs.shared_standard_service,
            needs.provider_executed_builtin,
            needs.anthropic_schema_client_tool,
        )
    )
    if execution_flags > 1:
        raise ValueError("choose one execution boundary for a capability")
    if needs.provider_executed_builtin:
        execution = "server-built-in-tool"
        boundary = "anthropic-service"
    elif needs.anthropic_schema_client_tool:
        execution = "anthropic-schema-client-tool"
        boundary = "application-sandbox"
    elif needs.shared_standard_service:
        execution = "mcp"
        boundary = "mcp-server"
    else:
        execution = "custom-client-tool"
        boundary = "application-service"
    return {
        "execution": execution,
        "procedure": "skill" if needs.reusable_procedure else "inline-instructions",
        "execution_boundary": boundary,
        "authorization_owner": "application-policy",
    }

View on GitHub (pinned to 39ea8a1c6d)

Solutions

1. Pick the single intended execution boundary and set only that flag (shared_standard_service for an existing standard service; provider_executed_builtin for web_search-like tools; anthropic_schema_client_tool for app-sandboxed custom code).
2. Pre-check the flag count and prompt the user to choose before calling choose_capability_surface.
3. Represent the boundary as an enum instead of three booleans so mutual exclusion is structural.
4. Catch the ValueError and re-surface it as a form validation error listing the conflicting flags.

Example fix

# before
needs.provider_executed_builtin = True
needs.anthropic_schema_client_tool = True
surface = choose_capability_surface(needs)
# ValueError: choose one execution boundary

# after
needs.provider_executed_builtin = True
needs.anthropic_schema_client_tool = False
surface = choose_capability_surface(needs)

EXECUTION_FLAGS = ("shared_standard_service", "provider_executed_builtin", "anthropic_schema_client_tool")
def one_boundary_selected(needs) -> bool:
    return sum(bool(getattr(needs, f)) for f in EXECUTION_FLAGS) <= 1

from typing import Literal
ExecutionBoundary = Literal["standard-service", "server-builtin", "client-tool"]
# model the boundary as one required field instead of three booleans

try:
    surface = choose_capability_surface(needs)
except ValueError:
    chosen = prompt_user_to_pick_one(EXECUTION_FLAGS)
    for f in EXECUTION_FLAGS:
        setattr(needs, f, f == chosen)
    surface = choose_capability_surface(needs)

When it happens

Trigger: Passing a needs object with two or more execution flags true, e.g. shared_standard_service=True plus provider_executed_builtin=True, or anthropic_schema_client_tool=True plus provider_executed_builtin=True. Reached via decision_lab and tests test_capability_surface_has_one_execution_boundary and test_skill_composes_with_an_execution_surface.

Common situations: Design-checklist tools where users tick every box; evolving a capability from an MCP service to a server built-in and leaving the old flag set; boolean-flag structs with no type-level mutual exclusion.

Related errors

• tool_use requires name and object input
• every content block needs a type
• max_attempts must be positive
• unsupported schema type: {expected}
• schema {name} must be a non-negative integer

AI-assisted analysis of rohitg00/ai-engineering-from-scratch@39ea8a1c6d (2026-08-26). Data as JSON: /api/errors/f463b2e8c1dbb5ca. Report an issue: GitHub.