Show task support hints in tools-get and tools-call example

Extract formatToolHints() combining annotations + task support, used by
both formatToolLine and formatToolDetail. tools-get now shows task:required
or task:optional in the hints bracket. The tools-call example includes
--task or [--task] accordingly.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc

Author: claude

src/cli/output.ts

@@ -237,6 +237,31 @@ export function formatToolAnnotations(annotations: Tool['annotations']): string
   return parts.length > 0 ? parts.join(', ') : null;
 }
 
+/**
+ * Get the task support mode for a tool ('required', 'optional', or undefined)
+ */
+export function getToolTaskSupport(tool: Tool): string | undefined {
+  const toolAny = tool as Record<string, unknown>;
+  const execution = toolAny.execution as Record<string, unknown> | undefined;
+  return execution?.taskSupport as string | undefined;
+}
+
+/**
+ * Format tool hints: annotations + task support mode.
+ * Returns a string like "destructive, open-world, task:required" or null if empty.
+ */
+export function formatToolHints(tool: Tool): string | null {
+  const parts: string[] = [];
+
+  const annotationsStr = formatToolAnnotations(tool.annotations);
+  if (annotationsStr) parts.push(annotationsStr);
+
+  const taskSupport = getToolTaskSupport(tool);
+  if (taskSupport) parts.push(`task:${taskSupport}`);
+
+  return parts.length > 0 ? parts.join(', ') : null;
+}
+
 /**
  * Convert a JSON Schema type definition to a simplified type string
  * e.g., { type: 'string' } -> 'string'
@@ -466,15 +491,8 @@ export function formatToolParamsInline(schema: Record<string, unknown>): string
 export function formatToolLine(tool: Tool): string {
   const bullet = chalk.dim('*');
   const params = formatToolParamsInline(tool.inputSchema as Record<string, unknown>);
-  const parts: string[] = [];
-  const annotationsStr = formatToolAnnotations(tool.annotations);
-  if (annotationsStr) parts.push(annotationsStr);
-  // Show task execution mode
-  const toolAny = tool as Record<string, unknown>;
-  const execution = toolAny.execution as Record<string, unknown> | undefined;
-  const taskSupport = execution?.taskSupport as string | undefined;
-  if (taskSupport) parts.push(`task:${taskSupport}`);
-  const suffix = parts.length > 0 ? ` ${chalk.gray(`[${parts.join(', ')}]`)}` : '';
+  const hintsStr = formatToolHints(tool);
+  const suffix = hintsStr ? ` ${chalk.gray(`[${hintsStr}]`)}` : '';
   return `${bullet} ${grayBacktick()}${chalk.cyan(tool.name)} ${params}${grayBacktick()}${suffix}`;
 }
 
@@ -536,10 +554,10 @@ export function formatToolDetail(tool: Tool): string {
     lines.push(chalk.bold(`# ${title}`));
   }
 
-  // Tool header: Tool: `name` [annotations]
-  const annotationsStr = formatToolAnnotations(tool.annotations);
-  const annotationsSuffix = annotationsStr ? ` ${chalk.gray(`[${annotationsStr}]`)}` : '';
-  lines.push(`${chalk.bold('Tool:')} ${inBackticks(tool.name)}${annotationsSuffix}`);
+  // Tool header: Tool: `name` [hints]
+  const hintsStr = formatToolHints(tool);
+  const hintsSuffix = hintsStr ? ` ${chalk.gray(`[${hintsStr}]`)}` : '';
+  lines.push(`${chalk.bold('Tool:')} ${inBackticks(tool.name)}${hintsSuffix}`);
 
   // Input args
   lines.push('');
@@ -612,11 +630,19 @@ function exampleValue(propSchema: Record<string, unknown>): string {
 export function formatToolCallExample(tool: Tool, sessionName?: string): string | null {
   const schema = tool.inputSchema as Record<string, unknown> | undefined;
   const properties = schema?.properties as Record<string, Record<string, unknown>> | undefined;
+  const session = sessionName || '<@session>';
+
+  // Build --task flag based on task support
+  const taskSupport = getToolTaskSupport(tool);
+  const taskFlag =
+    taskSupport === 'required' ? ' --task' : taskSupport === 'optional' ? ' [--task]' : '';
+
+  const bullet = chalk.dim('*');
 
   if (!properties || Object.keys(properties).length === 0) {
     // Tool takes no arguments — still show the simple call
-    const session = sessionName || '<@session>';
-    return `${chalk.bold('Call example:')}\n  mcpc ${session} tools-call ${tool.name}`;
+    const cmd = `mcpc ${session} tools-call ${tool.name}${taskFlag}`;
+    return `${chalk.bold('Call example:')}\n${bullet} ${grayBacktick()}${chalk.cyan(cmd)}${grayBacktick()}`;
   }
 
   const requiredNames = (schema?.required as string[]) || [];
@@ -632,13 +658,13 @@ export function formatToolCallExample(tool: Tool, sessionName?: string): string
     params.push(...optionalInOrder.slice(0, remaining));
   }
 
-  const session = sessionName || '<@session>';
   const argParts = params.map((name) => {
     const val = exampleValue(properties[name] ?? {});
     return `${name}:=${val}`;
   });
 
-  return `${chalk.bold('Call example:')}\n  mcpc ${session} tools-call ${tool.name} ${argParts.join(' ')}`;
+  const cmd = `mcpc ${session} tools-call ${tool.name} ${argParts.join(' ')}${taskFlag}`;
+  return `${chalk.bold('Call example:')}\n${bullet} ${grayBacktick()}${chalk.cyan(cmd)}${grayBacktick()}`;
 }
 
 /**

test/unit/cli/output.test.ts

@@ -56,6 +56,7 @@ import {
   formatHuman,
   logTarget,
   formatToolCallExample,
+  formatToolHints,
 } from '../../../src/cli/output.js';
 import type {
   Tool,
@@ -909,6 +910,65 @@ describe('formatToolCallExample', () => {
     const output = formatToolCallExample(tool);
     expect(output).toContain('<@session>');
   });
+
+  it('should include --task for task:required tools', () => {
+    const tool = {
+      name: 'long-run',
+      inputSchema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
+      execution: { taskSupport: 'required' },
+    } as unknown as Tool;
+
+    const output = formatToolCallExample(tool, '@s');
+    expect(output).toContain('--task');
+    expect(output).not.toContain('[--task]');
+  });
+
+  it('should include [--task] for task:optional tools', () => {
+    const tool = {
+      name: 'maybe-async',
+      inputSchema: { type: 'object', properties: {} },
+      execution: { taskSupport: 'optional' },
+    } as unknown as Tool;
+
+    const output = formatToolCallExample(tool, '@s');
+    expect(output).toContain('[--task]');
+  });
+});
+
+describe('formatToolHints', () => {
+  it('should combine annotations and task support', () => {
+    const tool = {
+      name: 'test',
+      inputSchema: { type: 'object', properties: {} },
+      annotations: { destructiveHint: true, openWorldHint: true },
+      execution: { taskSupport: 'required' },
+    } as unknown as Tool;
+
+    const hints = formatToolHints(tool);
+    expect(hints).toContain('destructive');
+    expect(hints).toContain('open-world');
+    expect(hints).toContain('task:required');
+  });
+
+  it('should return null when no annotations and no task support', () => {
+    const tool: Tool = {
+      name: 'plain',
+      inputSchema: { type: 'object', properties: {} },
+    };
+
+    expect(formatToolHints(tool)).toBeNull();
+  });
+
+  it('should show only task support when no annotations', () => {
+    const tool = {
+      name: 'async-only',
+      inputSchema: { type: 'object', properties: {} },
+      execution: { taskSupport: 'optional' },
+    } as unknown as Tool;
+
+    const hints = formatToolHints(tool);
+    expect(hints).toBe('task:optional');
+  });
 });
 
 describe('formatServerDetails', () => {