Detect structural issues in PLAN.md: duplicate tasks, multiple current entries, and completed tasks with open subtasks. Validate plan health to ensure accurate project tracking.
Structure lint: duplicates, multiple current, complete-with-open-tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_path | No | Optional path to PLAN.md (relative to cwd or absolute). Default: walk up from cwd to nearest PLAN.md. |
Changes observed during successful MCP inspections.
v0.7.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing safety and side effects. It implies read-only analysis via 'lint' but never states that nothing is modified, what output is produced, or whether failures (issues found) affect the exit code. The listed check categories give some context but not enough for an agent to predict the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, naming the tool type as 'Structure lint' before listing what it checks. It avoids redundancy with the schema and contains no filler. However, it is a fragment rather than a complete sentence, which slightly reduces clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description should explain what the result looks like and confirm the operation is non-destructive. It lists the lint categories but omits how the tool reports issues and what an agent should do with the result. The missing behavioral details make it incomplete for safe autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents plan_path fully with default behavior (walk up to nearest PLAN.md) and absolute/relative usage, so schema coverage is 100%. The description adds no additional meaning about the parameter; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the operation as a 'structure lint' and enumerates specific checks (duplicates, multiple current, complete-with-open-tasks), making it clear this is a validation tool for the plan. However, 'lint' is not a plain verb and the resource is implied rather than stated. It is distinguishable from sibling tools like show_plan or create_plan because it checks rather than displays or edits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool instead of siblings. There is no mention of a workflow, such as validating a plan before starting an iteration, or any alternative tool to use when simply viewing the plan. Usage must be inferred entirely from the 'lint' label.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.