jadx-headless-mcp has 19 well-structured tools with consistent naming (verb_noun pattern: jadx.open, jadx.list, jadx.close, jadx.search, jadx.xref.to, jadx.callgraph). All tools have descriptions (avg ~80 chars, within 10-1024 range). Input schemas are present with typed parameters and descriptions. However, output schemas are NOT documented, the gen_tools_doc.py script explicitly states 'MCP's tools/list only declares input schema, has no output schema' and '凭空写一份返回值文档等于给自己制造一个必然漂移的第二事实源' (writing return docs creates a second source of truth that drifts). This is a critical gap: LLMs cannot plan downstream calls without knowing what fields to expect. Error handling is minimal, no recovery guidance, no categorization of retryable vs fatal errors. Parameter descriptions are adequate but lack format/range constraints (e.g., max_bytes defaults to 32768 but no min/max declared). Session parameter semantics are documented in jadx.help output but not in schema itself.

• Document output schemas for all tools. Create a separate OUTPUTS.md or inline schema definitions showing field names, types, and descriptions for each tool's response. This enables LLMs to plan multi-step workflows.
• Add error handling guidance to tool descriptions. State what errors can occur, whether they are retryable, and what the agent should do next. E.g., 'If session not found, call jadx.list to see available sessions.'
• Declare parameter constraints in schema. Add minimum/maximum for numeric params (e.g., limit: 1-100), patterns for strings (e.g., cursor format), and enums for fixed options (e.g., action: ['stats', 'clear']).
• Move session semantics into schema. Add a 'sessionSemantics' annotation or required field indicator to each tool's schema so agents understand parameter requirements without calling jadx.help first.
• Enhance pagination responses. Return total_count and next_cursor in paginated results so agents know when to stop iterating and can fetch remaining items efficiently.

Inferred effective spec: <=2025-11-25.

• Relies on Stateful initialize / Mcp-Session-Id (removed; protocol is stateless) - make each request self-contained