Loading ToolBench
MCP server that turns any JSON catalog into query tools for AI agents. Point it at a catalog URL or file; agents get filtering, grouping, ranking, and schema discovery.
catalog-mcp demonstrates solid tool design with consistent naming (verb_noun pattern), comprehensive parameter schemas using Zod, and detailed descriptions. All 7 tools follow a clear read-only query pattern. However, output schemas are documented only in descriptions and code comments, not formally in the tool registration. Parameter descriptions are strong (70-150 chars avg), but some lack explicit format/constraint guidance. Error handling returns structured responses but lacks recovery guidance (e.g., 'try catalog_schema first'). Tool annotations (readOnlyHint, idempotentHint) are present and correct. No critical gaps, but output documentation could be more formal.
Group records by a field and count each value, most common first. Array fields count each element. Optional filter applies first.
Fetch a single record by its key field. Returns { found, record }.
Filter, sort, and page through catalog records. Returns { count, total_matching, total_records, records }. Use catalog_schema first if you are unsure which fields exist. Example: filter {"eq":{"condition":"used"},"max":{"price":30000},"has":{"features":["Solar"]}}, sort_by "price".
Field inventory inferred from the records themselves: type, coverage, numeric min/max, and sample values for categorical fields. Call this first when exploring an unfamiliar catalog.
Record count, source, cache age, and optional numeric summaries (count/min/max/mean/median) for the fields you name.
Rank records by a numeric field with an optional filter. Example: sort_by "price", sort_dir "asc", filter {"has":{"features":["Bunkhouse"]}} = cheapest records with that feature.
Output schemas not formally documented in tool registration. Descriptions mention return structure (e.g., '{ count, total_matching, total_records, records }') but LLMs cannot parse this as machine-readable schema. catalog_query, catalog_get, catalog_count_by, catalog_top, catalog_values, catalog_stats all lack explicit outputSchema definitions.
Error responses lack recovery guidance. toError() returns only 'Error: {message}' without suggesting next steps. E.g., when catalog_query fails due to invalid filter, should suggest 'Call catalog_schema to see available fields' or 'Check filter syntax: eq, min, max, has, contains.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 64 | 2025-06-18+ | v2 |
All distinct values of a field with occurrence counts, most common first. The reliable way to learn a categorical field's vocabulary before filtering on it.
catalog_schema and catalog_stats descriptions are brief (75 chars) and lack guidance on when to call them. Should explicitly state 'Call this first when exploring an unfamiliar catalog' and 'Use this to understand data distribution before filtering.'
Filter parameter description includes example values ('eq', 'min', 'max', 'has', 'contains') inline. LLMs may treat these as the only valid keys. Should use formal constraint documentation or enum-like structure instead.
catalog_get key parameter description says 'Numbers are matched loosely' but does not explain what 'loosely' means (string coercion? numeric comparison?). Should clarify: 'Matched as strings after coercion; e.g., key=123 matches record with id="123" or id=123.'