The "capabilities over API mirror" framing is the right mental model, and it takes a few embarrassing false starts before it clicks. The moment it clicked for me was realizing the AI client doesn't know your data model — it only knows what the tool description says. A tool called get_documents with a vague description never gets called correctly; find_invoices_by_vendor_and_date_range with a two-line description that includes the expected output format hits on the first try, consistently.

The stdio→HTTP migration point is also underrated — most tutorials skip it because they don't model concurrent connections or session state. For multi-tenant setups, per-session context isolation is the piece most examples handle poorly or not at all.