From a861de1fb67c2a86535a0a75fe283f289acd9e1f Mon Sep 17 00:00:00 2001 From: Dave Date: Thu, 27 Aug 2026 07:50:17 +0200 Subject: [PATCH] docs(hermes): bump tool count + add 'three quote-creation tools' callout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hermes filed WFDASH-dev-ask-quotes-create.md on 2026-08-26 claiming `quotes.create` doesn't exist. It does — registered at src/app/api/mcp/route.ts:1131, REST at /api/v1/quotes/create, added 2026-08-15 in Phase G gap-fill, documented as Recipe 7 in docs/agents/workflows.md. The agent's actual failure was discovery, not a real gap. Two doc-only changes to keep this from recurring: 1. Tool count 125 → 141 (live count), recipe count 7 → 9 (live count) 2. New prominent "Three quote-creation tools — don't confuse them" section right under the intro listing all three paths (quotes.create / quotes.ingest_from_email / quotes.create_from_email) with the common failure mode explicitly called out. Recipe 7 already covers the walk-in workflow; this surfaces the contrast up front so the agent sees it during session-startup instead of after it has already picked the wrong tool. No code change. No FEATURE-REQUESTS.md entry — the tool isn't a gap. Co-Authored-By: Claude --- docs/agents/hermes-skill.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/agents/hermes-skill.md b/docs/agents/hermes-skill.md index 8d92dee..7c610ee 100644 --- a/docs/agents/hermes-skill.md +++ b/docs/agents/hermes-skill.md @@ -1,7 +1,7 @@ # WFDASH MCP — Hermes Skill You are wired to the **WFDASH business MCP** at `/api/mcp` -(JSON-RPC over HTTPS, bearer-token auth). 125 tools. PocketBase +(JSON-RPC over HTTPS, bearer-token auth). 141 tools. PocketBase backend. Owner: Dave. Run by an SME bearings import / industrial supply business in Cape Town (SAST, UTC+2). @@ -10,13 +10,35 @@ supply business in Cape Town (SAST, UTC+2). > > - `docs/api-mcp-layer.md` — full tool catalogue (auto-generated, > grouped by resource family, names + descriptions + inputSchemas). -> - `docs/agents/workflows.md` — seven end-to-end recipes (supplier +> - `docs/agents/workflows.md` — nine end-to-end recipes (supplier > invoice → receive, order split, partial collection, bulk pricing, -> partial approve + split, sprint claim, walk-in quote). **Always -> read this before chaining more than one tool call.** +> partial approve + split, sprint claim, walk-in quote, walk-in +> order + supplements, daily summary). **Always read this before +> chaining more than one tool call.** > - `src/app/api/mcp/FEATURE-REQUESTS.md` — the backlog of MCP gaps. > Read it so you don't try to call a tool that doesn't exist. +## Three quote-creation tools — don't confuse them + +There are **three** MCP tools that produce a new quote. Pick by where +the data came from, not by what feels closest: + +| Tool | When to use | Source | +|---|---|---| +| `quotes.create` | **Walk-in / manual** — operator types "make me a quote for John", or you extracted items from a PDF / phone-call / WhatsApp that has no inbound email. Customer + company + items passed directly. | `POST /api/v1/quotes/create` | +| `quotes.ingest_from_email` | **Inbound RFQ email, preferred path.** Stamps `ai_status="pending"` and returns immediately; the background processor extracts items via Claude against the email body + attachments. Use this whenever the customer actually emailed in. | `POST /api/v1/quotes/ingest-from-email` | +| `quotes.create_from_email` | **Legacy** — same email shape, but the caller passes a pre-extracted `extracted_items[]` array (no AI run). Only use this when you're calling on behalf of a parser that already did the extraction. | `POST /api/v1/quotes/create-from-email` | + +**Common failure mode:** agents reach for `quotes.create_from_email` +when they should be using `quotes.create`. The email path silently +drops `customer` / `company` / `items` args (it requires an actual +`subject` + parsed body), rewrites `email_message_id` to a +`synth-…@wfdash.local` sentinel, and lands on the +`Unknown Sender` placeholder customer. The result looks like a +"quote was created" but is orphaned to garbage data that needs a PB +admin to repair. If you don't have an inbound email, you want +`quotes.create` — never `quotes.create_from_email`. + ## Identity - **Language**: English. Default to British spelling. Mirror user's