docs(mcp): make tool docs match the 32 registered tools

docs/mcp-server/tools.md

@@ -1,8 +1,8 @@
 # Available MCP Tools
 
-The StockTrim MCP Server provides **30 tools** for interacting with the StockTrim API,
-organized into **Foundation Tools** (21 direct API operations) and **Workflow Tools**
-(9 high-level business operations).
+The StockTrim MCP Server provides **32 tools** for interacting with the StockTrim API,
+organized into **Foundation Tools** (21 direct API operations), **Workflow Tools** (9
+high-level business operations), and **Session Preference Tools** (2).
 
 ## Safety and User Confirmation
 
@@ -317,13 +317,10 @@ required before execution. See
 
 ## Inventory Tools
 
-### `stocktrim_get_inventory`
+### `set_product_inventory`
 
-Get current inventory levels.
-
-### `stocktrim_set_inventory`
-
-Set inventory levels for products.
+Set inventory levels for products. (There is no inventory-read tool; read a product's
+`stock_on_hand` via `get_product` instead.)
 
 **Parameters:**
 
@@ -505,43 +502,19 @@ Create a new location.
 
 - `location` (object): Location data
 
-## Planning Tools
-
-### `stocktrim_run_order_plan`
-
-Run inventory planning and get recommended orders.
-
-**Parameters:**
-
-- `filter_criteria` (object, optional): Filtering options
-
-### `stocktrim_run_forecast`
-
-Trigger demand forecasting calculations.
-
-## Configuration Tools
-
-### `stocktrim_get_configuration`
+## Not Yet Available as MCP Tools
 
-Get system configuration values.
-
-**Parameters:**
-
-- `configuration_name` (string): Config key to retrieve
-
-## Bill of Materials Tools
-
-### `stocktrim_list_boms`
-
-List all bills of materials.
-
-### `stocktrim_create_bom`
-
-Create a new bill of materials.
-
-**Parameters:**
+These capabilities exist in the StockTrim Python client library but are **not** exposed
+as MCP tools yet. Use the client library directly until they are added:
 
-- `bom` (object): BOM data
+- **Order-plan queries** — `client.order_plan.query(...)`. Forecast/reorder data is
+  currently reached indirectly through `forecasts_get_for_products` and
+  `review_urgent_order_requirements`; there is no standalone `run_order_plan` tool.
+- **Forecast triggering** — surfaced via the `forecasts_update_and_monitor` workflow
+  tool, not a standalone `run_forecast` tool.
+- **Bill of materials** — `client.bill_of_materials` (note: StockTrim's `/api/boms`
+  endpoint is currently unreliable and may return 404 even when BOMs exist).
+- **Inventory read** and **system configuration** — no MCP tool yet.
 
 ## Next Steps
 

stocktrim_mcp_server/src/stocktrim_mcp_server/server.py

@@ -150,15 +150,17 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
 ### Foundation Tools (Direct API Access)
 Basic CRUD operations for direct data manipulation:
 
-**Products**: get_product, search_products, list_products, create_products, delete_products
-**Customers**: get_customer, list_customers, create_customers
-**Suppliers**: get_supplier, list_suppliers, create_suppliers
-**Inventory**: get_inventory, set_inventory
-**Orders**: create_sales_order, get_sales_orders, delete_sales_orders,
-           get_purchase_order, list_purchase_orders, create_purchase_order, delete_purchase_order
+**Products**: get_product, search_products, create_product, delete_product
+**Customers**: get_customer, list_customers
+**Suppliers**: get_supplier, list_suppliers, create_supplier, delete_supplier
+**Inventory**: set_product_inventory
+**Sales Orders**: create_sales_order, get_sales_orders, list_sales_orders, delete_sales_orders
+**Purchase Orders**: get_purchase_order, list_purchase_orders, create_purchase_order, delete_purchase_order
 **Locations**: list_locations, create_location
-**Planning**: run_order_plan, run_forecast
-**BOM**: list_boms, create_bom
+
+_Not currently exposed as MCP tools_ (use the Python client library directly):
+bill-of-materials operations, direct order-plan queries, and standalone forecast
+triggering. There is also no inventory-read, customer-create, or bulk-create tool.
 
 ### Workflow Tools (High-Level Operations)
 Intent-based tools that combine multiple operations:
@@ -175,10 +177,15 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
 
 **Product Configuration**:
 - configure_product: Update product settings (discontinue status, forecast configuration)
+- products_configure_lifecycle: Activate/deactivate/discontinue/unstock with impact analysis
 
 **Supplier Onboarding**:
 - create_supplier_with_products: Onboard new supplier with product mappings in one operation
 
+**Session Preferences**:
+- get_preferences / set_preferences: Read or set session-scoped filters
+  (category, location, supplier, days threshold) applied by the workflow tools
+
 ## Resources (Discovery & Context)
 
 Resources provide read-only access to StockTrim data for AI agents to explore and gather context
@@ -218,8 +225,8 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
 4. Review draft POs in StockTrim UI before approving
 
 **Approach B - Manual**:
-1. list_products → Get all products
-2. get_inventory → Check stock levels
+1. search_products(...) → Find candidate products
+2. get_product(code) → Inspect a product's stock_on_hand and supplier
 3. For low-stock items: create_purchase_order with appropriate quantities
 
 ### 2. Forecast Management
@@ -242,7 +249,7 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
    })
 
 **Approach B - Step by Step**:
-1. create_suppliers([{code: "SUP-NEW", name: "New Supplier Inc"}])
+1. create_supplier({code: "SUP-NEW", name: "New Supplier Inc"})
 2. For each product: Update product with supplier mapping
 
 ### 4. Product Configuration
@@ -260,10 +267,9 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
 
 **Steps**:
 1. get_customer("CUST-001") → Verify customer exists
-2. get_product("WIDGET-001") → Verify product exists and get details
-3. get_inventory → Check if sufficient stock available
-4. If in stock: create_sales_order({...})
-5. After order ships: set_inventory to deduct stock
+2. get_product("WIDGET-001") → Verify product exists and check stock_on_hand
+3. If in stock: create_sales_order({...})
+4. After order ships: set_product_inventory to deduct stock
 
 ## Best Practices
 
@@ -304,7 +310,7 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
 ```
 product = get_product("WIDGET-001")
 if product:
-    set_inventory({product_id: product.id, quantity: 100})
+    set_product_inventory({product_id: product.id, quantity: 100})
 else:
     # create product first
 ```
@@ -343,7 +349,8 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
 ## Rate Limiting & Performance
 
 - List operations return limited results - check total_count in responses
-- Batch operations (create_products, create_customers) are more efficient than loops
+- Prefer workflow tools (e.g. create_supplier_with_products) over many single-entity
+  calls when onboarding related data in one step
 - Forecast calculations can take minutes - use forecasts_update_and_monitor for progress
 - Order plan queries are cached - re-run forecasts if data seems stale