Synchronize requirements files to installed versions safely and atomically.
Single tool with comprehensive parameter schema and clear descriptions. Tool name follows verb_noun pattern (reqsync_sync). All 15 parameters have type definitions and descriptions. Output schema is documented via McpToolResult TypedDict. Error handling returns structured responses with exit codes and error messages. Descriptions are adequate but could be more LLM-optimized (10-50 chars). Parameter descriptions are clear but lack constraint hints (ranges, validation rules). Missing tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite WRITE risk designation.
Sync requirement files to installed versions.
Tool description is generic (45 chars) and lacks WHEN/WHY context. Should explain that this tool modifies files (dry_run=true by default makes it safe to test), its use in CI/CD pipelines, and distinction from manual pip freeze workflows.
Parameter descriptions lack validation hints. E.g., 'policy' accepts 4 enum values but description doesn't mention constraints; 'pip_timeout_sec' (default 900) lacks min/max bounds; 'path' lacks format guidance (relative vs absolute, glob patterns?). LLMs may pass invalid values.
Missing tool annotations despite WRITE risk. Tool should declare destructiveHint=true (modifies files) and idempotentHint=true (dry_run=true by default makes it safe for planning). These annotations guide agent behavior and retry strategies.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 59 | <=2025-11-25 | v2 |
| 2026-03-09 | D | 59 | - | v1 |
Error handling returns generic exception messages (str(error)) without recovery guidance. E.g., if pip fails or file is locked, response should suggest 'Ensure pip is available in the active virtualenv' or 'Check file permissions'. Pattern: recovery-guide.
Output schema (McpToolResult) includes error and result fields but lacks pagination or per-item status. If sync touches multiple files (follow_includes=true), agent cannot tell which file failed. Response should include per-file status.