Four tools with clear verb-noun naming (create_user, get_user, search_users, list_users) and basic descriptions. All tools have input schemas with typed parameters and descriptions. However, descriptions are minimal (10-40 chars), lacking context on WHEN to use each tool or dependencies between them. Output schemas are inferred from return type hints but not explicitly documented. Error handling exists but lacks recovery guidance. No tool annotations (readOnlyHint/destructiveHint). Pagination support present but limit/offset defaults are config-driven, not visible in schema.
Create a new CRM user.
Get a user by id.
List users with pagination.
Search semantically similar users.
Tool descriptions are too brief (10-40 chars). LLMs cannot determine WHEN to use search_users vs list_users, or whether create_user validates email format. Descriptions must explain purpose, prerequisites, and differentiation from similar tools.
Output schemas not explicitly documented in code. Return types are inferred from Python type hints (UserResponse, SearchUserResponse, list[UserResponse], int) but LLMs cannot see these. Must document field names, types, and meanings in tool descriptions or via structured schema declarations.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). create_user is destructive (WRITE risk) but LLMs have no signal that it modifies state. search_users and list_users are read-only but unmarked. Annotations guide agent planning and safety.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | <=2025-11-25 | v2 |
Error messages lack recovery guidance. _raise_domain_error and _raise_unexpected_error return generic RuntimeError strings. When DuplicateEmailError occurs, the LLM sees 'Email already exists' but has no hint to try search_users or suggest a different email. Errors must guide next steps.
Parameter defaults (top_k, limit, offset) are sourced from config (_CFG.search.default_top_k, _CFG.pagination.default_limit) and not visible in schema. LLMs cannot see what the defaults are. Defaults must be explicit in the schema or description.