webmcp-kit is a browser-based MCP tool framework with 11 well-defined tools across two example domains (flight booking and pizza shop). Tools have good naming conventions (verb_noun pattern) and structured schemas using Zod. However, several tools lack critical depth in parameter descriptions, and output schemas are not explicitly documented. Tool descriptions are present but vary in quality. The framework itself demonstrates solid engineering (TypeScript, Zod validation, mock support), but tool quality shows uneven parameter documentation and missing error handling guidance.
Tools (11)
addExtraswritesource verified73/100
Configure add-on options like checked bags, seat selection, and insurance
addToCartwritesource verified87/100
Add a pizza to the shopping cart
addTravelerwritesource verified82/100
Add a traveler profile to the current booking
checkoutdestructivesource verified78/100
Complete the order and checkout. Requires user confirmation.
clearCartwritesource verified73/100
Remove all items from the cart
getCartread onlysource verified73/100
Get the current shopping cart contents and total
getMenuread onlysource verified73/100
Get the pizza menu with all available pizzas, prices, and toppings
Output schemas not documented. No indication of what searchFlights, getMenu, reviewBooking, getCart, etc. return to the agent. LLMs cannot infer result structure and may fail to chain tools or extract required IDs for downstream calls.
Parameter descriptions lack actionable detail on constraints and expected values. For example, addExtras describes 'checkedBags' as 'Total checked bags for the booking' but does not specify valid range (0-10? 0-5?), unit clarification, or whether it applies per passenger or per booking.
Document the return value (output schema) for every tool. For searchFlights, explicitly state: returns array of {flightId, airline, departure, arrival, price, availability}. For getMenu: returns {pizzas: [{id, name, price, toppings}], total}. This enables agents to chain calls and extract required IDs.
Add constraints to numeric and string parameters. Change 'Total checked bags for the booking' to 'Total checked bags (0-5, applies to entire booking, not per passenger)'. Add min/max to addToCart quantity: 'quantity (1-10, total across size variants)'.
Add a 'confirm' boolean parameter to destructive tools (purchaseFlight, checkout) and document: 'Set to true to finalize. If false, returns dry-run summary.' This implements the confirmation-request pattern without blocking the agent.
Add pagination parameters to list-returning tools: 'limit (1-50, default 20) and offset or cursor for getMenu and searchFlights. Document: Returns paginated results; use offset+limit or next_cursor for large menus/result sets.'
Enhance error descriptions with recovery paths. Example for selectFlight: 'If error 'flight_not_found', call searchFlights again with adjusted date/class. If error 'sold_out', return list of alternatives via searchFlights with incremented date.'
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) for all tools. Mark searchFlights, getMenu, getCart, reviewBooking with readOnlyHint=true. Mark purchaseFlight and checkout with destructiveHint=true and idempotentHint=false to guide agent planning.
Score history
Overall score trend
↑ 4 points across a rubric change (v1 → v2)
58/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
58
2026-07-28+
v2
2026-03-09
D
54
-
v1
source verified
75/100
Finalize and purchase the current booking. Requires confirmation.
reviewBookingread onlysource verified73/100
Review current booking details and estimated total price
searchFlightsread onlysource verified90/100
Search available flights by route, date, passenger count, and cabin class
selectFlightwritesource verified82/100
Select one flight from the search results
Destructive tools (purchaseFlight, checkout) claim to require confirmation, but no confirmation mechanism is visible in the schema. Parameter schemas do not show a 'confirm' boolean or similar guard. Recovery guidance is absent, if the operation fails, the description does not tell the LLM what to do next.
Tools returning list-like data (getMenu, getCart, searchFlights) do not show pagination or limit parameters. If a menu has 100+ pizzas or a cart has hundreds of items, no mechanism exists to cap results. Context window risk.
Parameter descriptions do not explain error scenarios or recovery paths. When selectFlight fails (flight not found, flight full), the LLM receives no guidance on whether to search again or which tool to call next.
No error classification or categorization visible. Errors are not labeled as retryable, user-fixable, or fatal, so agents cannot determine the correct next action on failure.
reviewBooking and checkout lack clear indication of what information they return. Does reviewBooking return an itemized breakdown, totals, and booking confirmation ID? Does checkout return an order ID, receipt, or delivery address confirmation? Without explicit output documentation, agents cannot reliably chain operations.
reviewBookingcheckout
Specify what each READ_ONLY tool returns. For reviewBooking: include booking_id, item_summary (flight, travelers, add-ons), subtotal, taxes, total_price, estimated_confirmation_time. For getCart: include pizza_items (id, name, size, quantity, price each), total, empty boolean.
Document mutual exclusivity and dependencies in parameter descriptions. E.g., for checkout: 'deliveryAddress required if payment_method=card, optional if cash. paymentMethod defaults to card.'
Add enum constraints to checkout paymentMethod if only 'card' and 'cash' are valid (already shown), but also clarify in description: 'Payment method, card or cash. Card requires deliveryAddress; cash supports pickup.'
Provide examples of valid parameter combinations in tool descriptions, not as example values. E.g., for addToCart: 'Common: add 2 large pepperonis, 1 small margherita. Variants: quantity 1-10, size small|medium|large.'
Implement per-item error reporting for batch-like operations. If addTraveler is called for 3 passengers and 1 fails validation, return {success: [{firstName, lastName, age, passengerId}], failed: [{firstName, lastName, error: 'age must be >= 18'}]}.
Document idempotency guarantees. State for each tool: 'Safe to retry with identical parameters' (idempotent) or 'Each call creates new item, not safe to retry' (not idempotent). This is critical for agents deciding whether to retry on ambiguous failures.
Add input validation examples to parameter descriptions. E.g., addTraveler: 'First and last names: 1-50 chars, letters/hyphens/apostrophes only. Age: 0-150.' This prevents LLM from passing invalid formats.
Include chaining IDs in all responses. If selectFlight succeeds, it must return flight_id, booking_id (or temporary booking reference), and required_fields (e.g., ['travelers', 'extras']) so the agent knows what to do next without discovery calls.