Structured, machine-readable data from Turkish public construction unit-price (birim fiyat) catalogs. Exposes catalog parsing, diffing, and validation to an agent runtime.
Three well-named, verb-prefixed tools with clear, detailed descriptions (150 - 250 chars each). All parameters have types and descriptions. Input schemas are complete with proper JSON Schema. Output structure is documented in descriptions. Error handling returns structured dicts with 'error' field. Main gaps: no output schema formally documented, no enum constraints on 'pages' parameter, no explicit pagination guidance, and tool_diff lacks idempotency/retry semantics. Naming is strong (parse_, diff_, validate_); descriptions are LLM-optimized and explain WHAT, WHEN, and WHAT-RETURNS. Parameters are well-constrained (pdf_path: string, pages: optional string range, tolerance: float). Risk annotations (READ_ONLY) present but not formal tool annotations.
Diff two ÇŞB catalog years by poz code: price moves (delta + percent), added and removed pozes, unit changes, and pozes that gained or lost a printed price. `pages` is a 0-based range applied to both PDFs; `tolerance` (in TL) hides small price moves. Returns per-kind counts, the mean price %-change, and the individual changes — the year-over-year rate movement a single catalog can't show.
Parse a ÇŞB birim-fiyat catalog PDF into structured pozes: poz number, description, unit and unit price. `pages` is a 0-based page range like "8-20" (or a single index); omit it to read the whole document. Prices are only ever numbers the catalog actually printed in the price column; a category-title poz (e.g. "EVİYELER:") is left price-less on purpose. Returns per-page-set counts (priced / group_headers / price_gaps) plus the pozes.
Validate a parsed ÇŞB catalog against deterministic quality rules: duplicate poz codes, malformed codes, non-positive prices, priced pozes with no unit, and units outside the known set. Returns findings with severity (error/warning) and an `ok` flag — a rule-based check that catches parse/OCR slips without ML, never fixing or inventing anything.
Output schemas not formally documented in code. Descriptions explain what is returned (counts, pozes, findings) but no JSON Schema definition visible for response structure. LLMs cannot plan downstream tool calls without knowing exact response fields.
No formal tool annotations (readOnlyHint, destructiveHint, idempotentHint). Risk field in metadata says READ_ONLY but not exposed as MCP tool annotation. Agents cannot infer safety/retry semantics from tool definition alone.
'pages' parameter accepts free-form string ('8-20' or single index) with no enum or pattern constraint. Description explains format but LLMs may pass invalid ranges (e.g., '20-8', 'abc'). Should validate early and return actionable error.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | 2026-07-28+ | v2 |
Error handling returns {'error': str(exc)} for FileNotFoundError and ValueError. Error messages are honest but not actionable. Should guide LLM: 'PDF not found at /path/to/file. Check path and retry.' or 'Invalid page range: expected "8-20" or single index.'
tool_diff does not document idempotency or retry semantics. Parsing two PDFs and diffing is deterministic, but no explicit guarantee. Agents need to know: is it safe to retry if the call times out?