@planu/cli 5.7.6 → 5.7.7

package/dist/tools/register-platform-tools/design-stack-tools.js

@@ -67,17 +67,17 @@ export function registerDesignStackTools(server) {
         description: t('tools.challenge_spec.description'),
         annotations: { readOnlyHint: true },
         inputSchema: {
-            specId: SpecIdSchema.describe('Spec ID to challenge'),
+            specId: SpecIdSchema.describe('Spec ID to challenge. Must match pattern ^SPEC-\\d+$, max 50 characters.'),
             projectId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Project ID hash. Prefer projectPath — stays correct after context compaction.'),
+                .describe('Project ID hash. Prefer projectPath — stays correct after context compaction. Max 500 characters.'),
             projectPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Absolute path to project root. Derives projectId automatically — always correct even after context compaction.'),
+                .describe('Max 4096 characters. Absolute path to project root. Derives projectId automatically — always correct even after context compaction.'),
             focus: z
                 .array(ChallengeSpecFocusEnum)
                 .max(100)

package/dist/tools/register-spec-tools/analysis-tools.js

@@ -26,7 +26,7 @@ export const DeclaredDriftInputSchema = z.object({
         .string()
         .min(100)
         .max(10_000)
-        .describe('Why the implementation drifted from the approved architectural premise. Minimum 100 characters — becomes the reconciliation transition reason.'),
+        .describe('Min 100, max 10000 characters. Why the implementation drifted from the approved architectural premise — becomes the reconciliation transition reason.'),
 });
 import { handleSsrBackMigration } from '../ssr-back-migration.js';
 import { registerMigrateLegacySpecTool } from '../migrate-legacy-spec.js';
@@ -115,13 +115,17 @@ export function registerAnalysisTools(server) {
     server.registerTool('reconcile_spec', {
         description: t('tools.reconcile_spec.description'),
         inputSchema: {
-            specId: SpecIdSchema.describe('Spec ID to reconcile'),
-            projectId: z.string().max(500).optional().describe('Project ID hash. Prefer projectPath.'),
+            specId: SpecIdSchema.describe('Spec ID to reconcile. Must match pattern ^SPEC-\\d+$, max 50 characters.'),
+            projectId: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Project ID hash. Prefer projectPath. Max 500 characters.'),
             projectPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Absolute path to project root. Derives projectId automatically.'),
+                .describe('Absolute path to project root. Derives projectId automatically. Max 4096 characters.'),
             autoDetect: z
                 .boolean()
                 .optional()
@@ -132,11 +136,20 @@ export function registerAnalysisTools(server) {
                 .describe('Enable living spec mode: compare acceptance criteria against codebase, auto-mark criteria as met/pending/drift, update the ## Progress section of spec.md (default: false)'),
             changes: z
                 .array(z.object({
-                section: z.string().max(500),
-                originalValue: z.string().max(10_000),
-                newValue: z.string().max(10_000),
-                reason: z.string().max(10_000),
-                approved: z.boolean(),
+                section: z
+                    .string()
+                    .max(500)
+                    .describe('Max 500 characters. Spec section the change applies to.'),
+                originalValue: z
+                    .string()
+                    .max(10_000)
+                    .describe('Max 10000 characters. Current text being replaced.'),
+                newValue: z.string().max(10_000).describe('Max 10000 characters. Replacement text.'),
+                reason: z
+                    .string()
+                    .max(10_000)
+                    .describe('Max 10000 characters. Why the change is needed.'),
+                approved: z.boolean().describe('Whether the user approved this change.'),
             }))
                 .max(1000)
                 .optional()

package/dist/tools/register-spec-tools/core-spec-tools.js

@@ -18,7 +18,10 @@ import { handleTypeSafetyGate } from '../type-safety-gate.js';
 import { runWithTrustedLocalMcpContext } from '../../engine/lifecycle-reconciliation.js';
 /** init_project inputSchema — extracted to keep registerCoreSpecTools within line budget. */
 const INIT_PROJECT_INPUT_SCHEMA = {
-    projectPath: z.string().max(4096).describe('Absolute path to the project root'),
+    projectPath: z
+        .string()
+        .max(4096)
+        .describe('Absolute path to the project root. Max 4096 characters.'),
     mode: z
         .enum(['existing_project', 'new_project'])
         .optional()
@@ -27,18 +30,40 @@ const INIT_PROJECT_INPUT_SCHEMA = {
         .string()
         .max(4096)
         .optional()
-        .describe('Parent workspace path for explicit new_project onboarding'),
-    appName: z.string().max(500).optional().describe('Human-readable app name for new_project'),
+        .describe('Parent workspace path for explicit new_project onboarding. Max 4096 characters.'),
+    appName: z
+        .string()
+        .max(500)
+        .optional()
+        .describe('Human-readable app name for new_project. Max 500 characters.'),
     appSlug: z
         .string()
         .max(200)
         .optional()
-        .describe('Safe folder slug for new_project; must not contain path separators'),
-    projectType: z.string().max(500).optional().describe('Type of project being initialized'),
-    platform: z.string().max(500).optional().describe('Runtime/deployment platform'),
-    language: z.string().max(500).optional().describe('User-confirmed language'),
-    framework: z.string().max(500).nullable().optional().describe('User-confirmed framework'),
-    database: z.string().max(500).nullable().optional().describe('User-confirmed database'),
+        .describe('Safe folder slug for new_project; must not contain path separators. Max 200 characters.'),
+    projectType: z
+        .string()
+        .max(500)
+        .optional()
+        .describe('Type of project being initialized. Max 500 characters.'),
+    platform: z
+        .string()
+        .max(500)
+        .optional()
+        .describe('Runtime/deployment platform. Max 500 characters.'),
+    language: z.string().max(500).optional().describe('User-confirmed language. Max 500 characters.'),
+    framework: z
+        .string()
+        .max(500)
+        .nullable()
+        .optional()
+        .describe('Max 500 characters. User-confirmed framework.'),
+    database: z
+        .string()
+        .max(500)
+        .nullable()
+        .optional()
+        .describe('Max 500 characters. User-confirmed database.'),
     createDirectory: z
         .boolean()
         .optional()
@@ -162,7 +187,11 @@ export function registerCoreSpecTools(server) {
     server.registerTool('create_spec', {
         description: t('tools.create_spec.description'),
         inputSchema: {
-            title: z.string().min(1).max(500).describe('Title of the spec / user story'),
+            title: z
+                .string()
+                .min(1)
+                .max(500)
+                .describe('Title of the spec / user story. Max 500 characters.'),
             description: z
                 .string()
                 .max(10_000)
@@ -176,21 +205,25 @@ export function registerCoreSpecTools(server) {
                 .max(128)
                 .regex(/^[A-Za-z0-9._:-]+$/)
                 .optional()
-                .describe('Stable caller key. Retries return the exact committed create_spec result.'),
+                .describe('Must match pattern ^[A-Za-z0-9._:-]+$, max 128 characters. Stable caller key — retries return the exact committed create_spec result.'),
             projectPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Absolute path to the project root. Auto-detected from git root when omitted.'),
+                .describe('Max 4096 characters. Absolute path to the project root. Auto-detected from git root when omitted.'),
             type: SpecTypeEnum.optional().describe('Spec type (default: feature)'),
             scope: SpecScopeEnum.optional().describe('Spec scope (default: feature)'),
             target: SpecTargetEnum.optional().describe('Target area: frontend, backend, shared, fullstack, infrastructure, database'),
-            tags: z.array(z.string().max(500)).max(100).optional().describe('Tags for categorization'),
+            tags: z
+                .array(z.string().max(500))
+                .max(100)
+                .optional()
+                .describe('Tags for categorization. Each tag max 500 characters.'),
             feature: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Feature group tag (e.g. "Authentication", "Billing"). Added to tags for categorization. Flat structure — no subdirectories created.'),
+                .describe('Max 500 characters. Feature group tag (e.g. "Authentication", "Billing"). Added to tags for categorization. Flat structure — no subdirectories created.'),
             acFormat: SpecAcFormatEnum.optional().describe('SPEC-224: Format for acceptance criteria in spec.md. ' +
                 'checkbox (default) — markdown checkboxes (- [ ] criterion). ' +
                 'bdd — Gherkin Given-When-Then scenarios for BDD workflows.'),
@@ -242,12 +275,12 @@ export function registerCoreSpecTools(server) {
                 .string()
                 .max(500)
                 .optional()
-                .describe('Project ID (hash). Prefer projectPath if unknown.'),
+                .describe('Max 500 characters. Project ID (hash). Prefer projectPath if unknown.'),
             projectPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Absolute path to the project root. Used to derive projectId automatically.'),
+                .describe('Max 4096 characters. Absolute path to the project root. Used to derive projectId automatically.'),
             status: SpecStatusEnum.optional().describe('Filter by spec status'),
             type: SpecTypeEnum.optional().describe('Filter by spec type'),
             detail: z
@@ -275,28 +308,28 @@ export function registerCoreSpecTools(server) {
     server.registerTool('update_status', {
         description: t('tools.update_status.description'),
         inputSchema: {
-            specId: SpecIdSchema.describe('Spec ID to update'),
+            specId: SpecIdSchema.describe('Spec ID to update. Must match pattern ^SPEC-\\d+$ (e.g. SPEC-042), max 50 characters.'),
             projectId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Project ID (hash). Prefer projectPath if unknown.'),
+                .describe('Project ID (hash). Prefer projectPath if unknown. Max 500 characters.'),
             projectPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Absolute path to the project root. Used to derive projectId automatically.'),
+                .describe('Absolute path to the project root. Used to derive projectId automatically. Max 4096 characters.'),
             status: SpecStatusEnum.describe('New status'),
             sessionId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Agent/session ID performing this lifecycle transition.'),
+                .describe('Agent/session ID performing this lifecycle transition. Max 500 characters.'),
             modelId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Concrete model ID used for this transition. Can satisfy SDD model-routing evidence when it maps to the required tier.'),
+                .describe('Max 500 characters. Concrete model ID used for this transition. Can satisfy SDD model-routing evidence when it maps to the required tier.'),
             modelTierUsed: z
                 .enum(['max', 'implementation', 'review'])
                 .optional()
@@ -305,27 +338,27 @@ export function registerCoreSpecTools(server) {
                 .string()
                 .max(500)
                 .optional()
-                .describe('SHA-256 hash of the persisted context package used to prove context continuity across agents.'),
+                .describe('Max 500 characters. SHA-256 hash of the persisted context package used to prove context continuity across agents.'),
             handoffPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Path to the persisted handoff package generated by package_handoff. Required for implementing/done unless handoffArtifactId is provided.'),
+                .describe('Max 4096 characters. Path to the persisted handoff package generated by package_handoff. Required for implementing/done unless handoffArtifactId is provided.'),
             handoffArtifactId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('External handoff artifact ID when the host stores handoff evidence outside the filesystem.'),
+                .describe('Max 500 characters. External handoff artifact ID when the host stores handoff evidence outside the filesystem.'),
             reviewedBy: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Reviewer identity/evidence required before status=done.'),
+                .describe('Reviewer identity/evidence required before status=done. Max 500 characters.'),
             arbitratedBy: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Arbiter identity/evidence required before status=done.'),
+                .describe('Arbiter identity/evidence required before status=done. Max 500 characters.'),
             reconcileRequired: z
                 .boolean()
                 .optional()
@@ -339,8 +372,16 @@ export function registerCoreSpecTools(server) {
                 apiCostUsd: z.number().min(0).optional(),
                 humanCostUsd: z.number().min(0).optional(),
                 totalCostUsd: z.number().min(0).optional(),
-                completedAt: z.string().max(500).optional(),
-                notes: z.string().max(10_000).optional(),
+                completedAt: z
+                    .string()
+                    .max(500)
+                    .optional()
+                    .describe('ISO timestamp. Max 500 characters.'),
+                notes: z
+                    .string()
+                    .max(10_000)
+                    .optional()
+                    .describe('Free-text notes. Max 10000 characters.'),
             })
                 .optional()
                 .describe('Actual metrics for status = done. All fields optional (SPEC-1356): missing numeric fields default to 0, completedAt/notes are auto-filled when omitted.'),
@@ -348,7 +389,7 @@ export function registerCoreSpecTools(server) {
                 .string()
                 .max(10_000)
                 .optional()
-                .describe('Feedback or observations when sending a spec back (e.g., review→draft). Stored in the spec for the implementer to address.'),
+                .describe('Max 10000 characters. Feedback or observations when sending a spec back (e.g., review→draft). Stored in the spec for the implementer to address.'),
             force: z
                 .boolean()
                 .optional()
@@ -361,7 +402,7 @@ export function registerCoreSpecTools(server) {
                 .string()
                 .max(2000)
                 .optional()
-                .describe('SPEC-721: Required when forceStatus=true. ≥100 characters explaining why validate gate is bypassed.'),
+                .describe('SPEC-721: Required when forceStatus=true. ≥100 and <=2000 characters explaining why validate gate is bypassed.'),
             dry_run: z
                 .boolean()
                 .optional()
@@ -370,18 +411,24 @@ export function registerCoreSpecTools(server) {
                 .string()
                 .max(2000)
                 .optional()
-                .describe('SPEC-733: Required for reverse transitions (done→implementing, discarded→draft). Must be ≥30 chars explaining why the spec is being reopened.'),
+                .describe('Must be ≥30 and <=2000 chars. SPEC-733: Required for reverse transitions (done→implementing, discarded→draft), explaining why the spec is being reopened.'),
             reconciliationRequestId: z
                 .string()
                 .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u)
                 .optional()
-                .describe('Trusted local MCP only: lowercase UUID idempotency key for implementing to review reconciliation.'),
-            expectedImplementingTransitionId: z.string().max(500).optional(),
+                .describe('Must match pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ (lowercase UUID). ' +
+                'Trusted local MCP only: idempotency key for implementing to review reconciliation.'),
+            expectedImplementingTransitionId: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Max 500 characters. Idempotency guard: the transitionId returned by the prior implementing transition.'),
             implementationReviewDigest: z
                 .string()
                 .regex(/^sha256:[a-f0-9]{64}$/u)
                 .optional()
-                .describe('SHA-256 of the exact validation-report.json bytes. Required implementation evidence for status=done; for status=review it is valid only inside the complete trusted local-MCP reconciliation tuple.'),
+                .describe('Must match pattern ^sha256:[a-f0-9]{64}$ — the literal prefix "sha256:" followed by 64 lowercase hex characters. ' +
+                'SHA-256 of the exact validation-report.json bytes. Required implementation evidence for status=done; for status=review it is valid only inside the complete trusted local-MCP reconciliation tuple.'),
             forceApprove: z
                 .boolean()
                 .optional()
@@ -391,20 +438,27 @@ export function registerCoreSpecTools(server) {
     server.registerTool('update_status_batch', {
         description: 'Batch update many specs to the same status in one MCP execution. Uses the same transition rules as update_status and reports updated/skipped/failed per spec.',
         inputSchema: {
-            specIds: z.array(SpecIdSchema).min(1).describe('Spec IDs to update'),
-            projectId: z.string().max(500).optional().describe('Project ID, if known'),
+            specIds: z
+                .array(SpecIdSchema)
+                .min(1)
+                .describe('Spec IDs to update. Each must match pattern ^SPEC-\\d+$, max 50 characters.'),
+            projectId: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Project ID, if known. Max 500 characters.'),
             projectPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Absolute project root. Preferred when projectId is unknown.'),
+                .describe('Absolute project root. Preferred when projectId is unknown. Max 4096 characters.'),
             status: SpecStatusEnum.exclude(['done']).describe('New status for all specs. Batch supports draft, review, approved, implementing, and discarded; close done specs individually with full evidence.'),
             dryRun: z.boolean().optional().describe('Preview the batch without mutating any spec.'),
             reviewNotes: z
                 .string()
                 .max(10_000)
                 .optional()
-                .describe('Optional notes for each transition.'),
+                .describe('Optional notes for each transition. Max 10000 characters.'),
             evidence: z
                 .record(z.string(), z.object({
                 modelTierUsed: z
@@ -429,8 +483,8 @@ export function registerCoreSpecTools(server) {
     server.registerTool('estimate', {
         description: t('tools.estimate.description'),
         inputSchema: {
-            specId: SpecIdSchema.describe('Spec ID to estimate'),
-            projectId: z.string().max(500).describe('Project ID'),
+            specId: SpecIdSchema.describe('Spec ID to estimate. Must match pattern ^SPEC-\\d+$ (e.g. SPEC-042), max 50 characters.'),
+            projectId: z.string().max(500).describe('Project ID. Max 500 characters.'),
         },
         outputSchema: EstimateOutputSchema,
     }, safeTracked('estimate', async (args) => handleEstimate(args)));
@@ -450,7 +504,7 @@ export function registerCoreSpecTools(server) {
     server.registerTool('validate', {
         description: t('tools.validate.description'),
         inputSchema: {
-            specId: SpecIdSchema.describe('Spec ID to validate'),
+            specId: SpecIdSchema.describe('Spec ID to validate. Must match pattern ^SPEC-\\d+$ (e.g. SPEC-042), max 50 characters.'),
             mode: z
                 .literal('submit')
                 .default('submit')
@@ -459,12 +513,12 @@ export function registerCoreSpecTools(server) {
                 .string()
                 .max(500)
                 .optional()
-                .describe('Project ID hash. Prefer projectPath — stays correct after context compaction.'),
+                .describe('Project ID hash. Prefer projectPath — stays correct after context compaction. Max 500 characters.'),
             projectPath: z
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Absolute path to project root. Derives projectId automatically — always correct even after context compaction.'),
+                .describe('Max 4096 characters. Absolute path to project root. Derives projectId automatically — always correct even after context compaction.'),
         },
         outputSchema: ValidateOutputSchema,
         annotations: {

package/dist/tools/tool-registry/core-tools.js

@@ -51,7 +51,12 @@ const coreToolsRegistry = [
         name: 'session_checkpoint',
         description: 'Persist a compact, bounded session checkpoint to planu/session-context.md for the next session.',
         schema: {
-            projectPath: z.string().trim().min(1).max(4096),
+            projectPath: z
+                .string()
+                .trim()
+                .min(1)
+                .max(4096)
+                .describe('Absolute path to the project root. Max 4096 characters.'),
         },
         handler: handleSessionCheckpoint,
         annotations: {
@@ -66,9 +71,20 @@ const coreToolsRegistry = [
         name: 'get_job',
         description: 'Read the durable state and latest checkpoint or result for a local Planu job.',
         schema: {
-            operationId: z.string().trim().min(1).max(128),
-            projectId: z.string().trim().min(1).max(128),
-            workspaceId: z.string().trim().min(1).max(128).optional(),
+            operationId: z
+                .string()
+                .trim()
+                .min(1)
+                .max(128)
+                .describe('Job operation ID. Max 128 characters.'),
+            projectId: z.string().trim().min(1).max(128).describe('Project ID hash. Max 128 characters.'),
+            workspaceId: z
+                .string()
+                .trim()
+                .min(1)
+                .max(128)
+                .optional()
+                .describe('Workspace ID. Max 128 characters.'),
         },
         handler: handleGetJob,
         annotations: {
@@ -84,9 +100,20 @@ const coreToolsRegistry = [
         name: 'restart_job',
         description: 'Restart a cancelled or failed durable job and schedule its typed executor.',
         schema: {
-            operationId: z.string().trim().min(1).max(128),
-            projectId: z.string().trim().min(1).max(128),
-            workspaceId: z.string().trim().min(1).max(128).optional(),
+            operationId: z
+                .string()
+                .trim()
+                .min(1)
+                .max(128)
+                .describe('Job operation ID. Max 128 characters.'),
+            projectId: z.string().trim().min(1).max(128).describe('Project ID hash. Max 128 characters.'),
+            workspaceId: z
+                .string()
+                .trim()
+                .min(1)
+                .max(128)
+                .optional()
+                .describe('Workspace ID. Max 128 characters.'),
         },
         handler: handleRestartJob,
         annotations: {
@@ -257,12 +284,16 @@ const coreToolsRegistry = [
         name: 'planu_status',
         description: 'Get a compact world-snapshot of the current Planu project state in one call: active spec (in-progress), next recommended spec (highest-priority approved), queue count, git state (staged/modified files), and an actionable suggestion. Designed to return the full picture in ≤150 tokens.',
         schema: {
-            projectPath: z.string().min(1).max(4096).describe('Absolute path to project root'),
+            projectPath: z
+                .string()
+                .min(1)
+                .max(4096)
+                .describe('Max 4096 characters. Absolute path to project root.'),
             projectId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Project ID (optional — derived from projectPath if omitted)'),
+                .describe('Max 500 characters. Project ID (optional — derived from projectPath if omitted).'),
         },
         handler: async (args) => handlePlanStatus(args),
         annotations: { readOnlyHint: true },
@@ -544,17 +575,17 @@ const coreToolsRegistry = [
             description: z
                 .string()
                 .max(10_000)
-                .describe('Free-form description: what you want to build, your problem, or your request'),
+                .describe('Max 10000 characters. Free-form description: what you want to build, your problem, or your request.'),
             projectId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Project ID or project path (used for context loading and focus persistence)'),
+                .describe('Max 500 characters. Project ID or project path (used for context loading and focus persistence).'),
             sessionId: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Session ID (overrides projectId for focus tracking)'),
+                .describe('Max 500 characters. Session ID (overrides projectId for focus tracking).'),
             scenario: z
                 .enum(['new_project', 'existing_project', 'concrete_problem'])
                 .optional()
@@ -567,28 +598,44 @@ const coreToolsRegistry = [
                 .string()
                 .max(4096)
                 .optional()
-                .describe('Parent workspace path that should contain a new project folder'),
-            appName: z.string().max(500).optional().describe('Human-readable new app name'),
+                .describe('Max 4096 characters. Parent workspace path that should contain a new project folder.'),
+            appName: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Max 500 characters. Human-readable new app name.'),
             appSlug: z
                 .string()
                 .max(200)
                 .optional()
-                .describe('Safe folder name for the new app; must not contain path separators'),
-            projectType: z.string().max(500).optional().describe('Kind of project to create'),
-            platform: z.string().max(500).optional().describe('Runtime or deployment platform'),
-            language: z.string().max(500).optional().describe('User-confirmed programming language'),
+                .describe('Max 200 characters. Safe folder name for the new app; must not contain path separators.'),
+            projectType: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Max 500 characters. Kind of project to create.'),
+            platform: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Max 500 characters. Runtime or deployment platform.'),
+            language: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Max 500 characters. User-confirmed programming language.'),
             framework: z
                 .string()
                 .max(500)
                 .nullable()
                 .optional()
-                .describe('User-confirmed framework, null for no framework'),
+                .describe('Max 500 characters. User-confirmed framework, null for no framework.'),
             database: z
                 .string()
                 .max(500)
                 .nullable()
                 .optional()
-                .describe('User-confirmed database, null for no database'),
+                .describe('Max 500 characters. User-confirmed database, null for no database.'),
             createDirectory: z
                 .boolean()
                 .optional()
@@ -603,12 +650,12 @@ const coreToolsRegistry = [
                 .min(0)
                 .max(10)
                 .optional()
-                .describe('Current step index for new_project flow (0–2)'),
+                .describe('Maximum 10. Current step index for new_project flow (0–2).'),
             targetTool: z
                 .string()
                 .max(500)
                 .optional()
-                .describe('Planu tool name to check ambiguity for before calling it'),
+                .describe('Max 500 characters. Planu tool name to check ambiguity for before calling it.'),
             checkFocus: z
                 .boolean()
                 .optional()
@@ -617,12 +664,12 @@ const coreToolsRegistry = [
                 .string()
                 .max(10_000)
                 .optional()
-                .describe('Explicitly declare a new session objective'),
+                .describe('Max 10000 characters. Explicitly declare a new session objective.'),
             planContent: z
                 .string()
                 .max(10_000)
                 .optional()
-                .describe('Plan Mode output to convert into a spec. Paste the plan markdown here to extract ACs and route to create_spec.'),
+                .describe('Max 10000 characters. Plan Mode output to convert into a spec. Paste the plan markdown here to extract ACs and route to create_spec.'),
         },
         handler: (args) => handleFacilitate(args),
         annotations: { readOnlyHint: false },