{"record":{"id":"f463b2e8c1dbb5ca","repo":"rohitg00/ai-engineering-from-scratch","slug":"choose-one-execution-boundary-for-a-capability","errorCode":null,"errorMessage":"choose one execution boundary for a capability","messagePattern":"choose one execution boundary for a capability","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"certifications/claude/lessons/10-tool-use-and-agentic-loops/code/main.py","lineNumber":63,"sourceCode":"class CapabilityNeeds:\n    \"\"\"Separate executable capability from optional reusable procedure.\"\"\"\n\n    reusable_procedure: bool = False\n    shared_standard_service: bool = False\n    provider_executed_builtin: bool = False\n    anthropic_schema_client_tool: bool = False\n\n\ndef choose_capability_surface(needs: CapabilityNeeds) -> dict[str, str]:\n    execution_flags = sum(\n        (\n            needs.shared_standard_service,\n            needs.provider_executed_builtin,\n            needs.anthropic_schema_client_tool,\n        )\n    )\n    if execution_flags > 1:\n        raise ValueError(\"choose one execution boundary for a capability\")\n    if needs.provider_executed_builtin:\n        execution = \"server-built-in-tool\"\n        boundary = \"anthropic-service\"\n    elif needs.anthropic_schema_client_tool:\n        execution = \"anthropic-schema-client-tool\"\n        boundary = \"application-sandbox\"\n    elif needs.shared_standard_service:\n        execution = \"mcp\"\n        boundary = \"mcp-server\"\n    else:\n        execution = \"custom-client-tool\"\n        boundary = \"application-service\"\n    return {\n        \"execution\": execution,\n        \"procedure\": \"skill\" if needs.reusable_procedure else \"inline-instructions\",\n        \"execution_boundary\": boundary,\n        \"authorization_owner\": \"application-policy\",\n    }","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/rohitg00/ai-engineering-from-scratch/blob/39ea8a1c6d0b61f071226eff7ede4d4105fed820/certifications/claude/lessons/10-tool-use-and-agentic-loops/code/main.py#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Pre-check the flag count and prompt the user to choose before calling choose_capability_surface.","Represent the boundary as an enum instead of three booleans so mutual exclusion is structural.","Catch the ValueError and re-surface it as a form validation error listing the conflicting flags."],"exampleFix":"# before\nneeds.provider_executed_builtin = True\nneeds.anthropic_schema_client_tool = True\nsurface = choose_capability_surface(needs)\n# ValueError: choose one execution boundary\n\n# after\nneeds.provider_executed_builtin = True\nneeds.anthropic_schema_client_tool = False\nsurface = choose_capability_surface(needs)","handlingStrategy":"validation","validationCode":"EXECUTION_FLAGS = (\"shared_standard_service\", \"provider_executed_builtin\", \"anthropic_schema_client_tool\")\ndef one_boundary_selected(needs) -> bool:\n    return sum(bool(getattr(needs, f)) for f in EXECUTION_FLAGS) <= 1","typeGuard":"from typing import Literal\nExecutionBoundary = Literal[\"standard-service\", \"server-builtin\", \"client-tool\"]\n# model the boundary as one required field instead of three booleans","tryCatchPattern":"try:\n    surface = choose_capability_surface(needs)\nexcept ValueError:\n    chosen = prompt_user_to_pick_one(EXECUTION_FLAGS)\n    for f in EXECUTION_FLAGS:\n        setattr(needs, f, f == chosen)\n    surface = choose_capability_surface(needs)","preventionTips":["Prefer an enum/radio selection over boolean checkboxes for execution boundary.","Count set flags before calling and force a choice if more than one is set.","When migrating a capability to a new boundary, unset the old flag in the same change."],"tags":["python","tool-design","mutual-exclusion","validation"],"backgroundTag":"conflicting-options","analyzedSha":"39ea8a1c6d0b61f071226eff7ede4d4105fed820","analyzedAt":"2026-08-26T03:13:46.626Z","schemaVersion":2},"datasetVersion":"2026-08-26T07:17:17.940Z"}