Last week I spent forty minutes debugging an agent that refused to do something it was fully allowed to do.

The fix was one sentence. The lesson took longer.

The setup

My agent has capability levels. At the lowest level it can't write source files at all. I wanted that refusal to be visible, not just an absence — so instead of leaving the tool unregistered, I registered a stub that always fails:

@agent.tool(name="write_project_file")