# Technical Writing Prover MCP for AI Agents AI Agent Connect > Technical Writing Prover validates your technical documentation against professional standards. It checks for a defined audience, Diátaxis structure, working code examples, active voice, and completeness. Instead of letting your AI agent produce a wall of text that confuses users, this Connector forces it to prove the docs are actually ready for production by checking every specific requirement before it gives you the final output. ## Overview - **Category:** productivity - **Price:** Free - **Endpoint:** https://edge.vinkius.com/vk_preview_OWaZOabijYQqiXzNKgOGtWneCoMKT68VO6tDqnNd/ai-agent-connect - **Tags:** technical-writing, documentation, diataxis, developer-docs, api-docs, code-examples, style-guide, content-quality ## Description When you ask an AI to write documentation, it usually gives you a generic wall of text that sounds okay but fails in practice. It might target 'developers' without knowing if that's a student or a staff engineer, or it might include code snippets that don't actually run. This Connector changes that by forcing your agent to follow a rigorous validation process. It ensures your documentation follows the Diátaxis framework, which separates tutorials, how-to guides, references, and explanations so your readers don't get lost. It checks for active voice to remove ambiguity and verifies that every code block is copy-pasteable and tested on specific runtimes. If the AI tries to hand-wave a complex step or skip a prerequisite, the tool flags it and demands a fix. By using this Connector through the Vinkius catalog, you're not just asking for text; you're enforcing a standard of quality that prevents production outages and reduces support tickets. It turns your agent into a senior technical editor who refuses to sign off on anything less than perfect. Instead of guessing if your docs are good enough, you get a clear verdict. You get a checklist of specific improvements like adding error paths, defining clear roles, and providing measurable specs. This moves your content from a rough draft to a professional asset that actually helps your users succeed. ## Tools ### validate_technical_writing This tool checks your documentation for audience definition, Diátaxis structure, and working examples. It provides a specific verdict and coaching on how to fix identified gaps like missing error paths or vague terms. ## Prompt Examples **Prompt:** ``` Check if this API guide is clear enough for a junior dev. ``` **Response:** ``` It looks like you haven't defined who exactly is reading this. Are we targeting frontend developers integrating OAuth, backend engineers implementing JWT, or DevOps engineers configuring a gateway? Each needs different details. To make this effective, you should define: * **Role:** Frontend Engineer * **Expertise:** Mid-level, familiar with REST, new to OAuth 2.0 * **Prerequisites:** HTTP basics, JSON, curl usage * **Goal:** Authenticate a React SPA and handle token refresh ``` **Prompt:** ``` I need a how-to guide for setting up our database. Make sure it's not too wordy. ``` **Response:** ``` **Status: WRITING_PROVEN** * **Audience:** Mid-level backend engineers with Node.js prerequisites. * **Structure:** Diátaxis how-to with progressive disclosure (basic $ ightarrow$ scoped $ ightarrow$ rotation). * **Examples:** curl + Node.js fetch tested on Node 20 with expected responses. * **Clarity:** Active voice used, all terms defined, zero ambiguity. * **Completeness:** Prerequisites versioned, three error codes documented with headers, edge cases (expired/revoked/concurrent rotation) included. This documentation is ready for publication and should significantly reduce support tickets. ``` **Prompt:** ``` Review our current auth docs. Are there any missing error steps? ``` **Response:** ``` You have some completeness gaps that need to be addressed before this is ready for production: 1. **Missing Prerequisites:** You need to list the specific versions for kubectl, minikube, Docker, and minimum system requirements. 2. **No Error Handling:** You need to explain what happens if 'kubectl apply' fails. For example, show the ImagePullBackOff or CrashLoopBackOff error, explain the cause, and provide the fix. 3. **Vague Next Steps:** Instead of telling them to 'consult the documentation,' provide a specific link to the next tutorial, such as 'Expose your application with a Service.' Also, make sure to address edge cases like a namespace already existing or a port already being bound. ``` ## Capabilities ### Define specific reader roles Forces the agent to identify the exact expertise level and goals of the target audience. ### Apply Diátaxis structure Organizes content into tutorials, how-tos, references, or explanations to improve navigation. ### Verify copy-pasteable code Ensures every code block is tested on specific runtimes and includes expected outputs. ### Remove passive voice Identifies and fixes ambiguous phrasing to ensure clear, direct instructions. ### Check completeness Verifies that prerequisites, error paths, and next steps are fully documented. ## Use Cases ### API Documentation Audit A developer wants to know if their new Auth API guide is clear enough for a frontend user. They ask their agent to audit the draft using validate_technical_writing. ### Tutorial Verification A team wants to make sure their 'Getting Started' guide actually works for beginners. The agent checks for prerequisites and tested code blocks. ### Internal Knowledge Base A manager wants to turn messy Slack threads into structured internal how-to guides. The agent organizes the content into a Diátaxis-compliant structure. ### Style Guide Enforcement A company wants to ensure all documentation across 50 products uses the same active voice. The agent identifies and fixes passive language across the board. ## Benefits - Eliminate wall of text issues by forcing a Diátaxis structure that makes your documentation easy to scan. - Prevent production errors by verifying that every code example is copy-pasteable and tested on specific runtimes. - Reduce support tickets by requiring clear error paths and prerequisites for every technical task. - Standardize your brand voice by removing passive language and vague terms like 'it is recommended' using validate_technical_writing. - Save hours of manual auditing by letting your agent identify and fix documentation gaps automatically. ## How It Works The bottom line is you get production-ready documentation that actually helps users instead of confusing them. 1. Provide your documentation draft or a set of requirements into your AI client. 2. The agent calls the validation tool to check against the five decision pivots for audience, structure, examples, clarity, and completeness. 3. You get a WRITING_PROVEN status or a specific list of gaps that need to be fixed before publication. ## Frequently Asked Questions **Can Technical Writing Prover help me write better API docs?** Yes. It forces your AI agent to follow professional standards like the Diátaxis framework, ensuring your docs are structured correctly for the specific audience you are targeting. **Does this tool check for correct grammar?** It focuses on technical clarity. It specifically identifies and removes passive voice and vague terms to make your instructions direct and easy to follow. **How does it help with developer experience?** It ensures that developers don't get stuck on broken code examples or missing prerequisites, which reduces frustration and helps them complete their tasks faster. **Can I use it for internal company wikis?** Absolutely. It works for any technical documentation, including internal how-to guides and knowledge base articles, by enforcing a consistent and clear structure. **What is the Diátaxis framework it uses?** Diátaxis is a framework that helps organize documentation into four types: tutorials for learning, how-tos for tasks, references for information, and explanations for understanding. **Does it actually check if the code works?** It requires your agent to provide copy-pasteable blocks with expected outputs and specific runtime versions, ensuring the code is ready for production use. **Does it write documentation?** No. It validates that documentation meets five quality standards — defined audience, task-based structure, working examples, eliminated ambiguity, and verified completeness. It does not generate text. It forces you to prove your text is publication-ready. **What is the Diátaxis framework?** Diátaxis classifies documentation into four types based on reader need: tutorials (learning-oriented, guided steps), how-to guides (task-oriented, goal-focused), reference (information-oriented, API specs), and explanation (understanding-oriented, conceptual). Each type has different structural requirements. Mixing them produces documentation that serves none well. **Can it validate non-code documentation like architecture decision records?** Yes. For conceptual documents (ADRs, RFCs, design docs), the examplesWorking pivot applies to illustrative diagrams, data flow descriptions, or before/after comparisons instead of code blocks. The tool adapts to the document type — but the other four pivots (audience, structure, ambiguity, completeness) apply to every technical document regardless of type.