Prototype numeric humanization API built on normalized assets
Three tools with complete schemas and descriptions, but significant gaps in parameter documentation and error handling. Tool names follow verb_noun convention (get_, humanize_). Descriptions are present (100-200 chars) and explain WHAT the tools do. However, many parameters lack descriptions (e.g., 'variants', 'benchmark_register', 'approximation' in humanize_number have no guidance on when/why to use them). No error handling guidance, no recovery paths, no validation rules documented. Output schemas are not formally documented, responses are inferred from code (model_dump()). The batch tool (humanize_fragments) is well-composed but lacks pagination/limit guidance for large fragment lists.
Inspect humanumbers capabilities before rewriting: available languages, approximation levels, benchmark registers, and system preference options.
Rewrite a batch of numeric-heavy spec fragments into human-friendly wording with humanumbers. Useful when a source text contains many raw dimensions, weights, power figures, or distances.
Convert one numeric-heavy fragment into more natural wording using humanumbers directly from the project source tree.
Parameter descriptions missing or incomplete. 'variants' (int, 1-10), 'approximation' (enum: normal|rough), 'system_preference' (enum: auto|preserve|si), and 'benchmark_register' (enum: official|colloquial|rough|profane) lack guidance on when/why to use each option. LLMs cannot infer semantic meaning from names alone.
No error handling or recovery guidance. Tools do not document what happens on invalid input (e.g., unsupported language, malformed text, out-of-range variants). No actionable error messages or retry strategies documented.
Output schemas not formally documented. Responses are returned via model_dump() but the structure (fields, types, nesting) is not visible in tool definitions. LLMs cannot plan downstream calls without knowing what fields to expect.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 69 | 2026-07-28+ | v2 |
humanize_fragments lacks pagination/limit guidance. Accepts unbounded list of fragments with no documented max size or batching strategy. Large inputs could exhaust context or timeout.
Parameter 'mode' in humanize_number has enum constraint but no description explaining the difference between 'humanize' and 'benchmark' modes or when to use each.