Archy provides 8 tools with consistent schema structure and basic descriptions, but falls short of production grade. All tools have input schemas with type definitions and enums, which is positive. However, descriptions are generic and lack specificity about when to use each tool vs. alternatives. Parameter descriptions exist but are minimal (averaging ~40 chars, below the 72-char baseline). No output schemas are documented, LLMs cannot infer what fields to expect or how to chain results. Error handling is present but does not guide recovery. Tool naming follows verb_noun convention but several tools have overlapping semantics (e.g., generate_diagram_from_text vs. generate_diagram_from_text_with_ai) without clear differentiation in descriptions. Security: API keys and credentials are not visible in parameters (good), but no mention of scope declarations or permission gates. STDIO transport caps protocol readiness at 50; definition quality remains moderate due to missing output documentation and weak param descriptions.

• Document output schema for each tool. Specify the structure of the returned Mermaid code, diagram metadata, or exported image URL. Example: 'Returns {mermaid_code: string, diagram_type: string, validation_errors?: string[]}'. This enables LLMs to reason about downstream chaining.
• Distinguish generate_diagram_from_text vs. generate_diagram_from_text_with_ai in descriptions. Clarify: which requires OpenRouter API setup? Which is offline? When should an agent use each? Current names and descriptions are indistinguishable.
• Expand parameter descriptions with semantic guidance. Instead of 'Type of diagram to generate (flowchart, class, sequence, etc.)', write: 'Type of diagram: use flowchart for process steps, sequenceDiagram for interactions, classDiagram for object relationships, stateDiagram for state machines. See list_supported_diagram_types for full options and use cases.'
• Add explicit error handling documentation to each tool. Document failure modes: 'Returns error if mermaid syntax is invalid (e.g. unclosed brackets, undefined node references). Call validate_mermaid_syntax first if unsure. If GitHub API rate limits hit, wait 1 hour before retrying.' Include recovery guidance.
• Add tool annotations (readOnlyHint) to all 8 tools in the tools array. Declare 'readOnlyHint': true to signal to MCP clients that these tools do not modify state and are safe to execute in read-only contexts.
• Add commitLimit bounds validation. Document that commitLimit must be between 1 and 1000, with a default of 10. Currently unbounded, LLMs could pass absurd values that trigger API timeouts.