It is broken, especially in macroeconomics. On micro level, it is less problematic, although the main criticism of atq2119 in this thread is correct. The things wrong with it are roughly the supply and demand curves, the idea of equilibrium (assumption of its existence and uniqueness) and the approach that is inherently one-sided - one market at a time.
> When oil prices fall some producers seem to shut off their pumps. When restaurants raise their prices the people I know tend to cook at home more.
This is a strawman. These actually do not follow from the supply and demand itself, but rather from indifference curves (although utility theory has its problems too). Unfortunately, the theory of supply and demand doesn't treat multiple different products very well (even in substitution).
> I have a hard time imagining what those worlds would look like, so I expect your critique is far more nuanced.
I understand. You don't know the alternative, so you cannot imagine a different world.
If you want a good overview of the criticism, read Steve Keen's Debunking Economics. He has two chapters devoted to problems of the supply and demand theory.
And if you want see alternative, which is completely superior (gives intuitively similar results and more, requires less parameters and is easier to extend), I suggest the treatment in Blatt: Dynamic Economic Systems, first part. (This was also suggested to me courtesy of Steve Keen, but boy, it is good. Keen is not to everybody's taste, but everyone in economics should read Blatt. He is the most forgotten of all forgotten economists. Although I think the approach is not his own, I think it goes back to von Neumann, but I don't know how it is called.)
> then it seems we all agree on the general principles in broad strokes, and we don't need to throw out supply and demand after all
I disagree, we need to throw it out, because there is a much better alternative approach. See above.
The problems of general equilibrium approach are quite succinctly described in Keen: Debunking Economics. And compared to approach in Blatt: Dynamic Economic Systems, it's a disaster - too many parameters and assumptions for too little explaining power. It was a pretty decent way to describe the world when Walras came up with it; but it should have been obsoleted years ago.
I am not an economist, but I disagree strongly. The concept of supply and demand is a plague of economics theory, especially in the aggregate. It's a terrible idea, which should have been obsoleted years ago, and has much nicer alternatives. The basic (but not only) problem with it is that you're looking at one side of equation at a time.
There is a much nicer alternative treatment in J.M.Blatt: Dynamic Economic Systems, which uses Leontief matrices. Also, if you want to know where my criticism is coming from, read Steve Keen's Debunking Economics. And even he doesn't list all the issues with supply/demand analysis, although he hints at them in other chapters.
In mathematics, I wish more people knew about typed lambda calculus and its connection to mathematical logic. I think the fact that most mathematicians use predicate logic, while theorem provers use e.g. calculus of constructions is one of the big obstacles for more wide usage of automated theorem provers. But it's just a language barrier.
In economics, I wish more people knew about (I don't know the name, unfortunately) the approach to calculating of equilibrium prices that is described in J.M.Blatt's book Dynamic Economic Systems, and is based on input-output production matrices. It's a much more superior approach to the classical supply-demand analysis that dominates the textbooks, because it requires much less free parameters and assumptions.
As an aside, I would also recommend reading Thomas Piketty's Capital for 21st Century. IMHO it gives you a deeper historic perspective on economics than just couple decades back.
