Output schemas are not formally documented in tool definitions. LLMs cannot see Python type hints; they rely on explicit schema documentation in the tool metadata. Tools return OperationResult, PlanOut, CurrentContextOut, etc., but these schemas are not visible to the MCP protocol layer.
Enum constraints for status fields are described in text only ('TODO, IN_PROGRESS, PENDING_REVIEW, DONE, BLOCKED, DEFERRED') rather than formally declared as JSON Schema enums. This forces LLMs to parse text descriptions instead of selecting from constrained options.
update_planlist_plans
Recommendations
Explicitly document output schemas in tool metadata. For each tool, add a 'returns' field to the tool definition documenting field names, types, and what they represent. E.g., create_plan returns {plan_id: string, title: string, status: string, created_at: ISO8601 date}.
Convert all enum descriptions to formal JSON Schema enums. In the input schema for update_plan, change 'status' from type: string with description 'Optional new status (TODO, IN_PROGRESS, ...)' to type: string with enum: ['TODO', 'IN_PROGRESS', 'PENDING_REVIEW', 'DONE', 'BLOCKED', 'DEFERRED'].
Add explicit pagination metadata to list_plans and list_stories responses. Document total_count and has_more (or next_cursor) so LLMs know when to fetch additional pages. Describe this in both the tool description and inferred output schema.
Enhance delete_plan and delete_story descriptions with error handling and confirmation patterns. E.g., 'Delete a plan and all associated stories. This is irreversible. The operation will fail if the plan has dependent tasks elsewhere, call report(scope="plan") first to check dependencies. No confirmation is required; the caller bears responsibility.'
Add min/max constraints to numeric parameters in JSON Schema. For priority (0-5), add 'minimum': 0, 'maximum': 5 to the schema. For pagination limit, add 'minimum': 1, 'maximum': 100.
Consider splitting set_current_plan and set_current_story into dedicated functions: 'set_current_plan(plan_id: string)' for setting and 'list_plans_for_selection()' for discovery. Simpler contract, easier for LLMs to reason about.
Pagination tools (list_plans, list_stories) do not document total_count, has_more, or next_cursor in their schemas or descriptions. Without explicit pagination metadata, LLMs cannot determine if results are truncated or how to fetch subsequent pages.
delete_plan and delete_story tools lack error handling guidance and confirmation patterns. Descriptions are minimal (40 and 60 chars respectively) and do not mention recovery steps, retryability, or confirm-before-execute safeguards. Given these are destructive operations, this is a significant gap.
Parameter validation rules are implicit. The priority field is described as '0-5' in descriptions but not constrained in JSON Schema (no minimum/maximum). LLMs will pass values outside this range; validation must occur server-side but validation errors are not documented as tool responses.
Tools like set_current_plan and set_current_story have dual behavior (set with ID or list if no ID provided). This is documented but creates cognitive load for LLMs deciding whether to pass an ID or omit it. Consider splitting into separate tools (set_current_plan vs list_plans for selection).
Task tools (not shown in full source but referenced in changelog_tools.py) are registered and functional but their definitions are not included in the tool list provided. This incomplete visibility prevents full evaluation of the task management subsystem.
generate_changelog_entrygenerate_commit_message
Document relationship between tools explicitly. E.g., 'After calling create_story(), pass the returned story_id to set_current_story(story_id) to focus on that story before creating tasks within it.' This guides multi-step planning.
Implement tool annotations for destructive operations. Mark delete_plan, delete_story, and update_* tools with destructiveHint: true so clients can warn users before execution.
Document the task system fully by including all task tools (create_task, update_task, delete_task, list_tasks, get_task) in the tool definitions. Currently inferred from changelog tools but not explicitly registered as standalone tools in the provided source.