The BiznisWeb MCP server exposes 16 read-only tools for a GraphQL-backed e-shop API. Tool naming is verb-driven and clear (list_*, get_*), which is excellent. However, descriptions are consistently terse (10-50 chars), parameter documentation is sparse, and output schemas are entirely absent from the visible code. Parameter types are declared in JSON Schema but lack inline descriptions for what each parameter controls. Error handling is not visible in the provided source. The tool definitions are directly registered (not inferred), so full credit is possible on structure, but the description and schema documentation deficits are severe.

• Add a 50 - 200 character description to every tool that explains WHAT it does, WHEN to use it, and how it differs from similar tools. Example: 'List orders in this date range. Use for bulk lookups; call get_order() for detailed fields like invoice address.'
• Document the output schema for each tool. Show the JSON structure the LLM will receive: field names, types, and whether fields are always present or optional. Tools returning lists should document pagination (pageInfo, nextCursor, totalPages).
• Add a description to every input parameter. Specify valid values (enums), format/range, defaults, and dependencies. Example: 'lang_code: Language for product titles and descriptions (SK, CZ, EN; default SK). If omitted, defaults to SK.'
• Clarify pagination in list_* tool descriptions. State: 'Returns up to [limit] items. Use the nextCursor field to fetch subsequent pages. Provide cursor to params.offset for pagination.'
• Implement explicit error handling with recovery guidance. When a query fails or resource is not found, return: 'Order not found. Try searching with list_orders() to verify the order number exists.' Validate inputs early and return actionable error messages.
• Add tool annotations to all read-only tools using idempotentHint:true so agents know they are safe to retry without side effects.
• For tools with optional filters (list_orders, list_products), document the filtering behavior. 'Filter by status (ID from list_order_statuses()), from_date, to_date. Omit filters to return all results.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry