FlowMCP CLI exposes 15 tools with inconsistent quality. Most tools have descriptions (13/15), but descriptions are often vague or generic (e.g., 'Call a tool by name with JSON arguments'). Input schemas are present but minimal: most parameters lack type information beyond 'string' or 'boolean'. No output schemas are documented. Tool names use compound structures ('cache status', 'lists add-entry') rather than verb_noun convention, making intent ambiguous. Parameters like 'jsonArgs' and 'schemaPath' lack format constraints or validation guidance. Error handling is absent from visible definitions. No tool has documented return types or field mappings for chaining. The 'call' and 'private call' tools are particularly problematic: they accept arbitrary JSON strings, making it impossible for LLMs to validate inputs or understand expected outputs.

• Rename tools to verb_noun convention: 'invoke_tool' (not 'call'), 'list_shared_lists' (not 'lists'), 'inspect_cache_status' (not 'cache status'), 'run_diagnostics' (not 'doctor'). This lets LLMs parse intent from names alone.
• Document output schemas for all tools. E.g., 'Returns: {"tools": [{"name": string, "description": string, "inputSchema": object}], "count": number}'. LLMs need to know what fields to extract.
• Add format constraints to 'jsonArgs' and 'schemaPath' parameters. E.g., 'jsonArgs: Valid JSON string (e.g., {"key": "value"}). Must be parseable by JSON.parse().' and 'schemaPath: Absolute or relative path to a .mjs or .json schema file (e.g., ./schemas/my-schema.mjs).'
• Expand descriptions to 100-200 chars with WHEN/WHY context. E.g., 'Invoke a registered tool by name. Use this to call tools from the catalog. Returns the tool result or an error. If the tool is not found, call list-tools first to see available tools.'
• Add error recovery guidance. E.g., 'If schemaPath is invalid, error will be: "File not found at <path>". Check the path and try again.' This enables agents to self-correct without extra discovery calls.