Problem or Use Case

When a user requests image generation but no backend is available (FAL_KEY not set, no GPU, torch not installed), the agent silently attempts alternative workarounds instead of immediately informing the user what's missing.

Current behavior:

• User asks "create an image"
• image_generate tool is silently dropped from schema (check_fn returns False)
• Agent has no awareness of why - attempts PIL, web search, or other workarounds
• User never learns they need to set FAL_KEY or install torch

Expected behavior:

• User asks "create an image"
• Agent immediately responds: "Image generation is unavailable.
  To enable: set FAL_KEY (https://fal.ai) for cloud generation, or install torch with CUDA/MPS for local generation."

Related: #2445 (fail-fast for missing provider API keys - same pattern)

Proposed Solution

Option 1 - Directive system prompt:
Inject environment availability into system prompt when backends are missing, instructing agent not to attempt alternatives.

Option 2 - Handler-level guard (stronger):
Remove check_fn gating so tool always appears in schema. Move the availability check into the handler itself, returning a structured error with setup instructions. Model receives tool result and cannot ignore it.

A detect_image_generation_environment() probe function (following detect_audio_environment() pattern in voice_mode.py) would support both approaches.

Alternatives Considered

No response

Feature Type

New tool

Scope

Medium (few files, < 300 lines)

Contribution

• I'd like to implement this myself and submit a PR